اشتراکها
سلام؛ برای تبدیل معکوس (از شمسی به میلادی یا DateTime مربوط به JavaScript) هم میتوان از این API استفاده کرد؟
نظرات مطالب
معرفی System.Text.Json در NET Core 3.0.
چگونه UX یک API را بررسی میکنند؟
در پروژه angular2-validations، یک نمونه پیاده سازی اعتبارسنجی از راه دور یا RemoteValidation را میتوانید مشاهده کنید. این پیاده سازی مبتنی بر Promiseها است. در مطلب جاری پیاده سازی دیگری را بر اساس Observableها مشاهده خواهید کرد و همچنین ساختار آن شبیه به ساختار remote validation در ASP.NET MVC و jQuery Validator طراحی شدهاست.
نگاهی به ساختار طراحی اعتبارسنجی از راه دور در ASP.NET MVC و jQuery Validator
در نگارشهای مختلف ASP.NET MVC و ASP.NET Core، ویژگی Remote سمت سرور، سبب درج یک چنین ویژگیهایی در سمت کلاینت میشود:
که شامل موارد ذیل است:
- متن نمایشی خطای اعتبارسنجی.
- تعدادی فیلد اضافی که در صورت نیز از فرم استخراج میشوند و به سمت سرور ارسال خواهند شد.
- نوع روش ارسال اطلاعات به سمت سرور.
- یک URL که مشخص میکند، این اطلاعات باید به کدام اکشن متد در سمت سرور ارسال شوند.
سمت سرور هم میتواند یک true یا false را بازگشت دهد و مشخص کند که آیا اطلاعات مدنظر معتبر نیستند یا هستند.
شبیه به یک چنین ساختاری را در ادامه با ایجاد یک دایرکتیو سفارشی اعتبارسنجی برنامههای Angular تدارک خواهیم دید.
ساختار اعتبارسنجهای سفارشی async در Angular
در مطلب «نوشتن اعتبارسنجهای سفارشی برای فرمهای مبتنی بر قالبها در Angular» جزئیات نوشتن اعتبارسنجهای متداول فرمهای Angular را بررسی کردیم. این نوع اعتبارسنجها چون اطلاعاتی را به صورت Ajax ایی به سمت سرور ارسال نمیکنند، با پیاده سازی اینترفیس Validator تهیه خواهند شد:
اما زمانیکه نیاز است اطلاعاتی مانند نام کاربری یا ایمیل او را به سرور ارسال کنیم و در سمت سرور، پس از جستجوی در بانک اطلاعاتی، منحصربفرد بودن آنها مشخص شود یا خیر، دیگر این روش همزمان پاسخگو نخواهد بود. به همین جهت اینبار اینترفیس دیگری به نام AsyncValidator برای انجام اعمال async و Ajax ایی در Angular تدارک دیده شدهاست:
در این حالت امضای متد validate این اینترفیس به صورت ذیل است:
یعنی در اینجا هم میتوان یک Promise را بازگشت داد (مانند پیاده سازی که در ابتدای بحث عنوان شد) و یا میتوان یک Observable را بازگشت داد که در ادامه نمونهای از پیاده سازی این روش دوم را بررسی میکنیم؛ چون امکانات بیشتری را نسبت به Promiseها به همراه دارد. برای مثال در اینجا میتوان اندکی صبر کرد تا کاربر تعدادی حرف را وارد کند و سپس این اطلاعات را به سرور ارسال کرد. به این ترتیب ترافیک ارسالی به سمت سرور کاهش پیدا میکند.
پیاده سازی یک اعتبارسنج از راه دور مبتنی بر Observableها در Angular
ابتدا یک دایرکتیو جدید را به نام RemoteValidator به ماژول custom-validators اضافه کردهایم:
در ادامه کدهای کامل این اعتبارسنج را مشاهده میکنید:
توضیحات تکمیلی
ساختار Directive تهیه شده مانند همان مطلب «نوشتن اعتبارسنجهای سفارشی برای فرمهای مبتنی بر قالبها در Angular» است، تنها با یک تفاوت:
در اینجا بجای NG_VALIDATORS، از NG_ASYNC_VALIDATORS استفاده شدهاست.
سپس ورودیهای این دایرکتیو را مشاهده میکنید:
به این ترتیب زمانیکه appRemoteValidator به المانی اضافه میشود (نام selector این دایرکتیو)، سبب فعالسازی این اعتبارسنج میگردد.
- در اینجا توسط ویژگی remote-url، آدرس اکشن متد سمت سرور دریافت میشود.
- ویژگی remote-field مشخص میکند که اطلاعات المان جاری با چه کلیدی به سمت سرور ارسال شود.
- ویژگی remote-additional-fields مشخص میکند که علاوه بر اطلاعات کنترل جاری، اطلاعات کدامیک از کنترلهای دیگر را نیز میتوان به سمت سرور ارسال کرد.
یک نکته:
ذکر "remote-field="FirstName به معنای انتساب مقدار رشتهای FirstName به خاصیت متناظر با ویژگی remote-field است.
انتساب ویژهی "remoteUsernameValidationUrl" به [remote-url]، به معنای انتساب مقدار متغیر remoteUsernameValidationUrl که در کامپوننت متناظر این قالب مقدار دهی میشود، به خاصیت متصل به ویژگی remote-url است.
بنابراین اگر remote-field را نیز میخواستیم به همین نحو تعریف کنیم، ذکر '' جهت مشخص سازی انتساب یک رشته، ضروری میبود؛ یعنی درج آن به صورت:
ساختار مورد انتظار بازگشتی از سمت سرور
در کدهای فوق، یک چنین ساختاری باید از سمت سرور بازگشت داده شود:
برای نمونه این ساختار را میتوان توسط یک anonymous object ایجاد کرد و بازگشت داد:
در اینجا برای مثال بررسی میشود که آیا FirstName ارسالی از سمت کاربر، معادل Vahid است یا خیر؟ اگر بله، result به false تنظیم شده و همچنین پیام خطایی نیز بازگشت داده میشود.
همچنین اعتبارسنج سفارشی از راه دور فوق، پیامها را تنها از طریق HttpPost ارسال میکند. علت اینجا است که در حالت POST، برخلاف حالت GET میتوان اطلاعات بیشتری را بدون نگرانی از طول URL، ارسال کرد و همچنین کل درخواست، به علت وجود کاراکترهای غیرمجاز در URL (حالت GET، به درخواست یک URL از سرور تفسیر میشود)، برگشت نمیخورد.
تکمیل کامپوننت فرم ثبت نام کاربران
در ادامه تکمیل قالب user-register.component.html را مشاهده میکنید:
در مورد ویژگیهای appRemoteValidator پیشتر بحث شد. در اینجا تنها یک نکتهی جدید وجود دارد:
زمانیکه یک async validator مشغول به کار است و هنوز پاسخی را دریافت نکردهاست، خاصیت pending را به true تنظیم میکند. به این ترتیب میتوان پیام اتصال به سرور را نمایش داد:
همچنین چون در اینجا نحوهی طراحی شکست اعتبارسنجی به صورت ذیل است:
وجود کلید remoteValidation در مجموعهی username.errors، بیانگر وجود خطای اعتبارسنجی از راه دور است و به این ترتیب میتوان پیام دریافتی از سمت سرور را نمایش داد:
مزایای استفاده از Observableها در حین طراحی async validators
در کدهای فوق چنین مواردی را هم مشاهده میکنید:
در اینجا بجای کار مستقیم با control.value (روش متداول دسترسی به مقدار کنترل دریافتی در یک اعتبارسنج)، به رخداد valueChanges آن متصل شده و سپس پس از 400 میلیثانیه، جمع نهایی ورودی کاربر، در اختیار متد http.post برای ارسال به سمت سرور قرار میگیرد. به این ترتیب میتوان تعداد رفت و برگشتهای به سمت سرور را کاهش داد و به ازای هر یکبار فشرده شدن دکمهای توسط کاربر، سبب بروز یکبار رفت و برگشت به سرور نشد.
همچنین وجود و تعریف new Subject، دراینجا ضروری است و از نشتی حافظه و همچنین رفت و برگشتهای اضافهی دیگری به سمت سرور، جلوگیری میکند. این subject سبب میشود تا کلیه اعمال ناتمام پیشین، لغو شده (takeUntil) و تنها آخرین درخواست جدید رسیدهی پس از 400 میلیثانیه، به سمت سرور ارسال شود.
بنابراین همانطور که مشاهده میکنید، Observableها فراتر هستند از صرفا ارسال اطلاعات به سرور و بازگشت آنها به سمت کلاینت (استفادهی متداولی که از آنها در برنامههای Angular وجود دارد).
کدهای کامل این قسمت را از اینجا میتوانید دریافت کنید.
نگاهی به ساختار طراحی اعتبارسنجی از راه دور در ASP.NET MVC و jQuery Validator
در نگارشهای مختلف ASP.NET MVC و ASP.NET Core، ویژگی Remote سمت سرور، سبب درج یک چنین ویژگیهایی در سمت کلاینت میشود:
data-val-remote="کلمه عبور وارد شده را راحت می‌توان حدس زد!" data-val-remote-additionalfields="*.Password1" data-val-remote-type="POST" data-val-remote-url="/register/checkpassword"
- متن نمایشی خطای اعتبارسنجی.
- تعدادی فیلد اضافی که در صورت نیز از فرم استخراج میشوند و به سمت سرور ارسال خواهند شد.
- نوع روش ارسال اطلاعات به سمت سرور.
- یک URL که مشخص میکند، این اطلاعات باید به کدام اکشن متد در سمت سرور ارسال شوند.
سمت سرور هم میتواند یک true یا false را بازگشت دهد و مشخص کند که آیا اطلاعات مدنظر معتبر نیستند یا هستند.
شبیه به یک چنین ساختاری را در ادامه با ایجاد یک دایرکتیو سفارشی اعتبارسنجی برنامههای Angular تدارک خواهیم دید.
ساختار اعتبارسنجهای سفارشی async در Angular
در مطلب «نوشتن اعتبارسنجهای سفارشی برای فرمهای مبتنی بر قالبها در Angular» جزئیات نوشتن اعتبارسنجهای متداول فرمهای Angular را بررسی کردیم. این نوع اعتبارسنجها چون اطلاعاتی را به صورت Ajax ایی به سمت سرور ارسال نمیکنند، با پیاده سازی اینترفیس Validator تهیه خواهند شد:
export class EmailValidatorDirective implements Validator {
export class RemoteValidatorDirective implements AsyncValidator {
validate(c: AbstractControl): Promise<ValidationErrors | null> | Observable<ValidationErrors | null>;
پیاده سازی یک اعتبارسنج از راه دور مبتنی بر Observableها در Angular
ابتدا یک دایرکتیو جدید را به نام RemoteValidator به ماژول custom-validators اضافه کردهایم:
>ng g d CustomValidators/RemoteValidator -m custom-validators.module
import { Directive, Input } from "@angular/core"; import { AsyncValidator, AbstractControl, NG_ASYNC_VALIDATORS } from "@angular/forms"; import { Http, RequestOptions, Response, Headers } from "@angular/http"; import "rxjs/add/operator/map"; import "rxjs/add/operator/distinctUntilChanged"; import "rxjs/add/operator/takeUntil"; import "rxjs/add/operator/take"; import { Observable } from "rxjs/Observable"; import { Subject } from "rxjs/Subject"; @Directive({ selector: "[appRemoteValidator][formControlName],[appRemoteValidator][formControl],[appRemoteValidator][ngModel]", providers: [ { provide: NG_ASYNC_VALIDATORS, useExisting: RemoteValidatorDirective, multi: true } ] }) export class RemoteValidatorDirective implements AsyncValidator { @Input("remote-url") remoteUrl: string; @Input("remote-field") remoteField: string; @Input("remote-additional-fields") remoteAdditionalFields: string; constructor(private http: Http) {} validate(control: AbstractControl): Observable<{ [key: string]: any }> { if (!this.remoteUrl || this.remoteUrl === undefined) { return Observable.throw("`remoteUrl` is undefined."); } if (!this.remoteField || this.remoteField === undefined) { return Observable.throw("`remoteField` is undefined."); } const dataObject = {}; if ( this.remoteAdditionalFields && this.remoteAdditionalFields !== undefined ) { const otherFields = this.remoteAdditionalFields.split(","); otherFields.forEach(field => { const name = field.trim(); const otherControl = control.root.get(name); if (otherControl) { dataObject[name] = otherControl.value; } }); } // This is used to signal the streams to terminate. const changed$ = new Subject<any>(); changed$.next(); // This will signal the previous stream (if any) to terminate. const debounceTime = 400; return new Observable((obs: any) => { control.valueChanges .takeUntil(changed$) .take(1) .debounceTime(debounceTime) .distinctUntilChanged() .flatMap(term => { dataObject[this.remoteField] = term; return this.doRemoteValidation(dataObject); }) .subscribe( (result: IRemoteValidationResult) => { if (result.result) { obs.next(null); } else { obs.next({ remoteValidation: { remoteValidationMessage: result.message } }); } obs.complete(); }, error => { obs.next(null); obs.complete(); } ); }); } private doRemoteValidation(data: any): Observable<IRemoteValidationResult> { const headers = new Headers({ "Content-Type": "application/json" }); // for ASP.NET MVC const options = new RequestOptions({ headers: headers }); return this.http .post(this.remoteUrl, JSON.stringify(data), options) .map(this.extractData) .do(result => console.log("remoteValidation result: ", result)) .catch(this.handleError); } private extractData(res: Response): IRemoteValidationResult { const body = <IRemoteValidationResult>res.json(); return body || (<IRemoteValidationResult>{}); } private handleError(error: Response): Observable<any> { console.error("observable error: ", error); return Observable.throw(error.statusText); } } export interface IRemoteValidationResult { result: boolean; message: string; }
ساختار Directive تهیه شده مانند همان مطلب «نوشتن اعتبارسنجهای سفارشی برای فرمهای مبتنی بر قالبها در Angular» است، تنها با یک تفاوت:
@Directive({ selector: "[appRemoteValidator][formControlName],[appRemoteValidator][formControl],[appRemoteValidator][ngModel]", providers: [ { provide: NG_ASYNC_VALIDATORS, useExisting: RemoteValidatorDirective, multi: true } ] })
سپس ورودیهای این دایرکتیو را مشاهده میکنید:
export class RemoteValidatorDirective implements AsyncValidator { @Input("remote-url") remoteUrl: string; @Input("remote-field") remoteField: string; @Input("remote-additional-fields") remoteAdditionalFields: string;
<input #username="ngModel" required maxlength="8" minlength="4" type="text" appRemoteValidator [remote-url]="remoteUsernameValidationUrl" remote-field="FirstName" remote-additional-fields="email,password" class="form-control" name="username" [(ngModel)]="model.username">
- ویژگی remote-field مشخص میکند که اطلاعات المان جاری با چه کلیدی به سمت سرور ارسال شود.
- ویژگی remote-additional-fields مشخص میکند که علاوه بر اطلاعات کنترل جاری، اطلاعات کدامیک از کنترلهای دیگر را نیز میتوان به سمت سرور ارسال کرد.
یک نکته:
ذکر "remote-field="FirstName به معنای انتساب مقدار رشتهای FirstName به خاصیت متناظر با ویژگی remote-field است.
انتساب ویژهی "remoteUsernameValidationUrl" به [remote-url]، به معنای انتساب مقدار متغیر remoteUsernameValidationUrl که در کامپوننت متناظر این قالب مقدار دهی میشود، به خاصیت متصل به ویژگی remote-url است.
export class UserRegisterComponent implements OnInit { remoteUsernameValidationUrl = "api/Employee/CheckUser";
[remote-field]="'FirstName'"
ساختار مورد انتظار بازگشتی از سمت سرور
در کدهای فوق، یک چنین ساختاری باید از سمت سرور بازگشت داده شود:
export interface IRemoteValidationResult { result: boolean; message: string; }
namespace AngularTemplateDrivenFormsLab.Controllers { [Route("api/[controller]")] public class EmployeeController : Controller { [HttpPost("[action]")] [ResponseCache(Location = ResponseCacheLocation.None, NoStore = true)] public IActionResult CheckUser([FromBody] Employee model) { var remoteValidationResult = new { result = true, message = $"{model.FirstName} is fine!" }; if (model.FirstName?.Equals("Vahid", StringComparison.OrdinalIgnoreCase) ?? false) { remoteValidationResult = new { result = false, message = "username:`Vahid` is already taken." }; } return Json(remoteValidationResult); } } }
همچنین اعتبارسنج سفارشی از راه دور فوق، پیامها را تنها از طریق HttpPost ارسال میکند. علت اینجا است که در حالت POST، برخلاف حالت GET میتوان اطلاعات بیشتری را بدون نگرانی از طول URL، ارسال کرد و همچنین کل درخواست، به علت وجود کاراکترهای غیرمجاز در URL (حالت GET، به درخواست یک URL از سرور تفسیر میشود)، برگشت نمیخورد.
تکمیل کامپوننت فرم ثبت نام کاربران
در ادامه تکمیل قالب user-register.component.html را مشاهده میکنید:
<div class="form-group" [class.has-error]="username.invalid && username.touched"> <label class="control-label">User Name</label> <input #username="ngModel" required maxlength="8" minlength="4" type="text" appRemoteValidator [remote-url]="remoteUsernameValidationUrl" remote-field="FirstName" remote-additional-fields="email,password" class="form-control" name="username" [(ngModel)]="model.username"> <div *ngIf="username.pending" class="alert alert-warning"> Checking server, Please wait ... </div> <div *ngIf="username.invalid && username.touched"> <div class="alert alert-danger" *ngIf="username.errors.remoteValidation"> {{username.errors.remoteValidation.remoteValidationMessage}} </div> </div> </div>
زمانیکه یک async validator مشغول به کار است و هنوز پاسخی را دریافت نکردهاست، خاصیت pending را به true تنظیم میکند. به این ترتیب میتوان پیام اتصال به سرور را نمایش داد:
همچنین چون در اینجا نحوهی طراحی شکست اعتبارسنجی به صورت ذیل است:
obs.next({ remoteValidation: { remoteValidationMessage: result.message } });
مزایای استفاده از Observableها در حین طراحی async validators
در کدهای فوق چنین مواردی را هم مشاهده میکنید:
// This is used to signal the streams to terminate. const changed$ = new Subject<any>(); changed$.next(); // This will signal the previous stream (if any) to terminate. const debounceTime = 400; return new Observable((obs: any) => { control.valueChanges .takeUntil(changed$) .take(1) .debounceTime(debounceTime) .distinctUntilChanged()
همچنین وجود و تعریف new Subject، دراینجا ضروری است و از نشتی حافظه و همچنین رفت و برگشتهای اضافهی دیگری به سمت سرور، جلوگیری میکند. این subject سبب میشود تا کلیه اعمال ناتمام پیشین، لغو شده (takeUntil) و تنها آخرین درخواست جدید رسیدهی پس از 400 میلیثانیه، به سمت سرور ارسال شود.
بنابراین همانطور که مشاهده میکنید، Observableها فراتر هستند از صرفا ارسال اطلاعات به سرور و بازگشت آنها به سمت کلاینت (استفادهی متداولی که از آنها در برنامههای Angular وجود دارد).
کدهای کامل این قسمت را از اینجا میتوانید دریافت کنید.
کتاب الگوهای طراحی در سی شارپ 5، نوشتهی مهندس سید منصور عمرانی، انتشارات پندار پارس، جدیدترین کتاب در این زمینه است، البته چاپ کتاب مربوط میشه به مهر 92، کتاب خوب و کاربردیی هستش که نویسنده از تلفیق مثالها و نکات چند کتاب دیگه نوشته و نکات خودش رو هم آورده.
در حین انجام اعمال غیرهمزمان جاوا اسکریپتی مانند فراخوانیهای jQuery AJAX، برای مدیریت دریافت نتایج، عموما از یک سری callback استفاده میشود. برای مثال:
تا اینجا مشکلی به نظر نمیرسد. اما مورد ذیل چطور؟
در اینجا نیاز است پس از پایان کار عملیات Ajax ایی اول، عملیات دوم و پس از آن عملیات سومی انجام شود. همانطور که مشاهده میکنید، این نوع کدها به سرعت از کنترل خارج میشوند؛ خوانایی پایینی داشته و مدیریت استثناءهای رخ داده در آنها نیز در این بین مشکل است. از این جهت که خطاهای هر کدام به سطحی بالاتر منتقل نمیشود و باید همانجا محلی و داخل هر callback مدیریت گردد.
روشهای زیادی برای حل این مساله ارائه شدهاست و در حال حاضر کار کردن با promiseها متداولترین روش حل مدیریت فراخوانی کدهای همزمان جاوا اسکریپتی است. برای نمونه اگر از AngularJS استفاده کنید، سرویسهای آن برای دریافت اطلاعات از سرور، از یک چنین مفهومی استفاده میکنند.
Promise در جاوا اسکریپت چیست؟
شیء Promise، نمایانگر قراردادی است که در آینده میتواند مورد قبول واقع شود، یا رد گردد. بررسی این قرارداد، تنها یکبار میتواند رخ دهد (پذیرش یا رد آن). هنگامیکه این بررسی صورت گرفت (رد یا پذیرش آن و نه هردو)، یک callback برای اطلاع رسانی فراخوانی میگردد. سپس این callback میتواند یک Promise دیگر را سبب شود. به این ترتیب میتوان Promiseها را زنجیر وار به یکدیگر متصل کرد. برای نمونه jQuery به صورت توکار از promises پشتیبانی میکند:
متد get در jQuery یک شیء promise را بازگشت میدهد. در ادامه میتوان این نتیجه را توسط متد then، زنجیروار ادامه داد. متدی که به عنوان پارامتر به then ارسال میشود، یک callback بوده و پس از پایان کار promise قبلی رخ میدهد. آرگومانی که به این callback ارسال میشود، نتیجهی promise قبلی است. در حین اعمال jQuery Ajax، این callback تنها زمانی فراخونی میشود که عملیات قبلی موفقیت آمیز بوده باشد و data ارائه شده، اطلاعاتی است که توسط response دریافتی از سرور، دریافت گردیدهاست.
در این حالت، هر callback حداقل سه کار را میتواند انجام دهد:
الف) یک promise دیگر را بازگشت دهد. نمونه آنرا با return $.get در کدهای فوق ملاحظه میکنید.
ب) خاتمه عادی. همینجا کار promise با مقدار بازگشت داده شده، پایان مییابد.
ج) صدور یک استثناء. سبب برگشت خوردن و عدم پذیرش promise میشود.
استفاده از Promises در سایر کتابخانهها
jQuery پیاده سازی توکاری از promises دارد؛ اما سایر کتابخانهها، مانند AngularJS ایی که مثال زده شده چطور عمل میکنند؟
استانداردی به نام +Promises/A جهت یک دست سازی پیاده سازیهای promise در جاوا اسکریپت پیشنهاد شدهاست. jQuery نیمی از آنرا پیاده سازی کردهاست؛ اما کتابخانهی دیگری به نام Q Library، پیاده سازی نسبتا مفصلتری را از این استاندارد ارائه میدهد. فریم ورک AngularJS نیز در پشت صحنه از همین کتابخانه برای پیاده سازی promises استفاده میکند.
آشنایی با کتابخانه Q
استفاده مقدماتی از Q همانند مثالی است که از jQuery ملاحظه کردید.
اشیاء promise بازگشت داده شده توسط jQuery نیز توسط کتابخانه Q مورد پذیرش واقع میشوند:
علاوه بر اینها مفهومی به نام deferred objects نیز در کتابخانهی Q پیاده سازی شدهاست:
توسط deferred objects میتوان بررسی یک promise را به تاخیر انداخت. در مثال فوق، اولین callback فراخوانی شده به نام waitForClick، از اشیاء به تاخیر افتاده استفاده میکند. ابتدا توسط فراخوانی متد Q.defer، یک deferred object ایجاد میشود. در این بین اگر کاربر بر روی دکمهی OK کلیک کرد، با فراخوانی deferred.resolve، این promise مورد پذیرش واقع خواهد شد و یا اگر کاربر بر روی دکمهی cancel کلیک کند، با فراخوانی متد deferred.reject، این promise رد میگردد. نهایتا شیء promise توسط deferred.promise بازگشت داده خواهد شد.
در ادامه کار، اینبار متد then، دو callback را قبول میکند. Callback اول پس از پذیرش قرار داد و Callback دوم پس از رد قرار داد، فراخوانی خواهد گردید.
در رنجیره تعریف شده، اگر معادلی برای reject درنظر گرفته نشده باشد، مانند مثال ذیل:
Q به دنبال نزدیکترین متد callback گزارش خطای کار خواهد گشت. در این حالت متد failure1 در صورت شکست اولین promise فراخوانی خواهد شد.
همچنین اگر نتیجهی success1 با شکست مواجه شود نیز failure1 فراخوانی میگردد. اما باید درنظر داشت که شکست success2، توسط failure1 مدیریت نمیشود.
Promises در AngularJS
در AngularJS امکانات کتابخانه Q توسط پارامتری به نام q$ در اختیار سرویسهای برنامه قرار میگیرد (تزریق میشود):
در اینجا اگر دقت کنید، مباحث و عملکرد آن دقیقا مانند قبل است. ابتدا یک deferred object با فراخوانی متد q.defer ایجاد شده است. سپس با استفاده از امکانات توکار http آن (بجای استفاده از jQuery Ajax)، کار فراخوانی یک restful service صورت گرفته است (مثلا فراخوانی یک ASP.NET Web API). در صورت موفقیت کار، متد deferred.resolve و در صورت عدم موفقیت، متد deferred.reject فراخوانی شدهاست. نهایتا این سرویس، یک deferred.promise را بازگشت میدهد.
اکنون در کنترلری که قرار است از این سرویس استفاده کند، متد then کتابخانه Q را ملاحظه میکنید که دو Callback متناظر resolve و reject مدیریت promise بازگشت داده شده را به همراه دارد. اگر عملیات Ajaxایی موفقیت آمیز باشد، شیء books را مقدار دهی میکند و اگر خیر، پیامی را به کاربر نمایش خواهد داد.
پشتیبانی مرورگرهای جدید از استاندارد Promise
در حال حاضر کروم 32 و نگارشهای شبانه فایرفاکس، Promise را که جزئی از استاندارد JavaScript شدهاست، به صورت توکار و بدون نیاز به کتابخانههای جانبی، پشتیبانی میکنند.
در اینجا با فراخوانی window.Promise مشخص میشود که آیا مرورگر جاری از Promises پشتیبانی میکند یا خیر. سپس یک شیء promise ایجاد شده و این شیء توسط پارامترهای resolve و reject که هر دو تابع میباشند، کار مدیریت کدهای غیرهمزمان را انجام میدهد:
در مثال فوق ابتدا یک شیء Promise ایجاد شده است. این شیء استاندارد بوده و با کروم 32 قابل آزمایش است. سپس در callback ابتدایی آن میتوان یک عملیات AJAX ایی را انجام داد. اگر نتیجهی آن موفقیت آمیز بود، تنها کافی است پارامتر اول این callback را فراخوانی کنیم و اگر خیر، پارامتر دوم آنرا. برای استفاده از این شیء Promise ایجاد شده، میتوان از متد then استفاده کرد. این متد نیز در اینجا دو callback پذیرش و رد promise را میتواند دریافت کند. برای زنجیر کردن آن کافی است متد then، یک Promise دیگر را بازگشت دهد و از نتیجهی آن در then بعدی استفاده گردد.
$.get('http://site-url', function(data) { //این تابع پس از پایان کار عملیات ایجکسی در آینده فراخوانی خواهد شد });
$.get('http://site-url/0', function(data0) { // callback #1 $.get('http://site-url/1', function(data1) { // callback #2 $.post('http://site-url/2', function(data2) { // callback #3 }); }); });
روشهای زیادی برای حل این مساله ارائه شدهاست و در حال حاضر کار کردن با promiseها متداولترین روش حل مدیریت فراخوانی کدهای همزمان جاوا اسکریپتی است. برای نمونه اگر از AngularJS استفاده کنید، سرویسهای آن برای دریافت اطلاعات از سرور، از یک چنین مفهومی استفاده میکنند.
Promise در جاوا اسکریپت چیست؟
شیء Promise، نمایانگر قراردادی است که در آینده میتواند مورد قبول واقع شود، یا رد گردد. بررسی این قرارداد، تنها یکبار میتواند رخ دهد (پذیرش یا رد آن). هنگامیکه این بررسی صورت گرفت (رد یا پذیرش آن و نه هردو)، یک callback برای اطلاع رسانی فراخوانی میگردد. سپس این callback میتواند یک Promise دیگر را سبب شود. به این ترتیب میتوان Promiseها را زنجیر وار به یکدیگر متصل کرد. برای نمونه jQuery به صورت توکار از promises پشتیبانی میکند:
// returns a promise $.get('http://site-url/0') .then(function(data) { // callback 1 // returns a promise return $.get('http://site-url/1'); }) .then(function(data) { // callback 2 // returns a promise return $.post('http://site-url/2'); }) .then(function(data) { // callback 3 });
در این حالت، هر callback حداقل سه کار را میتواند انجام دهد:
الف) یک promise دیگر را بازگشت دهد. نمونه آنرا با return $.get در کدهای فوق ملاحظه میکنید.
ب) خاتمه عادی. همینجا کار promise با مقدار بازگشت داده شده، پایان مییابد.
ج) صدور یک استثناء. سبب برگشت خوردن و عدم پذیرش promise میشود.
استفاده از Promises در سایر کتابخانهها
jQuery پیاده سازی توکاری از promises دارد؛ اما سایر کتابخانهها، مانند AngularJS ایی که مثال زده شده چطور عمل میکنند؟
استانداردی به نام +Promises/A جهت یک دست سازی پیاده سازیهای promise در جاوا اسکریپت پیشنهاد شدهاست. jQuery نیمی از آنرا پیاده سازی کردهاست؛ اما کتابخانهی دیگری به نام Q Library، پیاده سازی نسبتا مفصلتری را از این استاندارد ارائه میدهد. فریم ورک AngularJS نیز در پشت صحنه از همین کتابخانه برای پیاده سازی promises استفاده میکند.
آشنایی با کتابخانه Q
استفاده مقدماتی از Q همانند مثالی است که از jQuery ملاحظه کردید.
Q.fcall(callback1) .then(callback2);
Q.fcall(function() { return $.get('http://my-url'); }) .then(callback3);
function waitForClick() { var deferred = Q.defer(); $('#okButton').click(function() { deferred.resolve(); }); $('#cancelButton').click(function() { deferred.reject(); }); return deferred.promise; } Q.fcall(waitForClick) .then(function() { // ok button was clicked }, function() { // cancel button was clicked });
در ادامه کار، اینبار متد then، دو callback را قبول میکند. Callback اول پس از پذیرش قرار داد و Callback دوم پس از رد قرار داد، فراخوانی خواهد گردید.
در رنجیره تعریف شده، اگر معادلی برای reject درنظر گرفته نشده باشد، مانند مثال ذیل:
Q.fcall(myFunction1) .then(success1) .then(success2, failure1);
همچنین اگر نتیجهی success1 با شکست مواجه شود نیز failure1 فراخوانی میگردد. اما باید درنظر داشت که شکست success2، توسط failure1 مدیریت نمیشود.
Promises در AngularJS
در AngularJS امکانات کتابخانه Q توسط پارامتری به نام q$ در اختیار سرویسهای برنامه قرار میگیرد (تزریق میشود):
var app = angular.module("myApp", []); app.factory('dataSvc', function($http, $q){ var basePath="api/books"; getAllBooks = function(){ var deferred = $q.defer(); $http.get(basePath).success(function(data){ deferred.resolve(data); }).error(function(err){ deferred.reject("service failed!"); }); return deferred.promise; }; return{ getAllBooks:getAllBooks }; }); app.controller('HomeController', function($scope, $window, dataSvc){ function initialize(){ dataSvc.getAllBooks().then(function(data){ $scope.books = data; }, function(msg){ $window.alert(msg); }); } initialize(); });
اکنون در کنترلری که قرار است از این سرویس استفاده کند، متد then کتابخانه Q را ملاحظه میکنید که دو Callback متناظر resolve و reject مدیریت promise بازگشت داده شده را به همراه دارد. اگر عملیات Ajaxایی موفقیت آمیز باشد، شیء books را مقدار دهی میکند و اگر خیر، پیامی را به کاربر نمایش خواهد داد.
پشتیبانی مرورگرهای جدید از استاندارد Promise
در حال حاضر کروم 32 و نگارشهای شبانه فایرفاکس، Promise را که جزئی از استاندارد JavaScript شدهاست، به صورت توکار و بدون نیاز به کتابخانههای جانبی، پشتیبانی میکنند.
if (window.Promise) { // Check if the browser supports Promises var promise = new Promise(function(resolve, reject) { //asynchronous code goes here }); }
if (window.Promise) { console.log('Promise found'); var promise = new Promise(function(resolve, reject) { // async if (result) { resolve(data); } else { reject('error'); } }); promise.then(function(data) { console.log('Promise fulfilled.'); }, function(error) { console.log('Promise rejected.'); }); } else { console.log('Promise not available'); }
دات نت 6 به همراه source generatorهای توکاری است که میتوانند کار serialization و deserialization نوع JSON را با کارآیی بسیار بیشتری انجام دهند؛ با آزمایشهایی که این بهبود را در حد 40 درصد سریعتر نسبت به حالت متداول آن نمایش میدهند و ... این مساله بسیار مهم است. از این جهت که این روزها، JSON را در همهجا مشاهده میکنیم؛ در Web APIها، در تنظیمات برنامهها، در ارسال پیامها بین برنامهها و غیره. بنابراین هرگونه بهبودی در زمینهی کارآیی serialization و deserialization آن، تاثیر بسیار قابل ملاحظهای را بر روی کارآیی کلی یک برنامه بجا خواهد گذاشت.
System.Text.Json source generator چیست؟
پایهی تمام اعمال serialization و deserialization در دات نت، استفاده از Reflection است که در زمینهی ارائهی برنامههایی با کارآیی بالا و با مصرف حافظهی پایین، بهینه عمل نمیکند. راهحل جایگزین استفاده از Reflection که در زمان اجرای برنامه رخ میدهد، به همراه دات نت 5 ارائه شد و source generators نام دارد. Source generators امکان تولید فایلهای #C را در زمان کامپایل برنامه میسر میکنند که نسبت به راهحل Reflection که در زمان اجرای برنامه فعال میشود، کارآیی بسیار بیشتری را ارائه میکنند. برای مثال به همراه دات نت 6، علاوه بر روش پیشفرض مبتنی بر Reflection ارائه شدهی توسط System.Text.Json، راه حل جدید امکان استفادهی از source generators توکار آن نیز پیش بینی شدهاست. کار اصلی آن، انجام تمام مراحلی است که پیشتر توسط Reflection در زمان اجرای برنامه صورت میگرفت، اینبار در زمان کامپایل برنامه و ارائهی آن به صورت از پیش آماده شده و مهیا.
مزایای این روش شامل موارد زیر است:
- بالا رفتن سرعت برنامه
- کاهش زمان آغاز اولیهی برنامه
- کاهش میزان حافظهی مورد نیاز برنامه
- عدم نیاز به استفادهی از System.Reflection و System.Reflection.Emit
- ارائهی Trim-compatible serialization که سبب کاهش اندازهی نهایی برنامه میشود. برای مثال در برنامههای Blazor میتوان با فعالسازی Trimming، کدهای استفاده نشده را از فایلهای بایناری نهایی حذف کرد. استفاده از source generators، با این روش سازگاری کاملی دارد.
مثالی از نحوهی کار با JSON در دات نت 6، توسط source generators آن
فرض کنید قصد داریم اعمال serialization و deserialization از نوع JSON را بر روی نمونههای کلاس زیر انجام دهیم:
اولین کاری که در این زمینه باید انجام شود، ایجاد یک کلاس خالی، با نامی دلخواه، اما مشتق شدهی از JsonSerializerContext است. در این حالت اخطارهایی را در IDE خود مبتنی بر نیاز به پیاده سازی تعدادی از متدهای این کلاس پایه دریافت میکنیم. اما ... ما قصد نداریم این متدها را پیاده سازی کنیم؛ Source generator قرار است اینکار را انجام دهد. به همین جهت این کلاس را partial تعریف کرده (تا source generator بتواند آنرا در فایلی دیگر تکمیل کند) و همچنین آنرا مزین به ویژگی JsonSerializable از نوع کلاسی که میخواهیم آنرا serialize کنیم، خواهیم کرد تا سبب فعال شدن source generator بر روی این کلاس شویم:
و ... همین! کدهای این کلاس partial توسط source generator در زمان کامپایل برنامه به صورت خودکار تولید و تکمیل میشوند.
پس از آن فقط کافی است MyJsonContext را به عنوان پارامتر متدهای جدید Serialize و یا Deserialize، به صورت زیر ارسال کنیم تا از آن استفاده شود:
متدهای جدید این API مبتنی بر source generators را در ادامه ملاحظه میکنید:
روش معرفی تنظیمات Serializer به Source generator
برای معرفی تنظیمات serialization و deserialization، برای مثال تهیهی خروجیهای CamelCase، میتوان از ویژگی JsonSourceGenerationOptions به صورت زیر استفاده کرد:
در این حالت مابقی کدها مانند قبل باقی خواهند ماند:
روش استفاده از JSON Source generators در برنامههای ASP.NET Core
در این نوع برنامهها، JsonSerializerContextها را میتوان توسط متد AddContext به صورت زیر به تنظیمات JSON برنامه معرفی کرد:
روش استفاده از JSON Source generators در برنامههای Blazor
البته در اینجا بیشتر منظور امکان استفادهی از آنها توسط HttpClient است که به صورت زیر توسط متد GetFromJsonAsync واقع در فضای نام System.Net.Http.Json، میسر شدهاست:
لیست کاملتر این API جدید به صورت زیر است:
System.Text.Json source generator چیست؟
پایهی تمام اعمال serialization و deserialization در دات نت، استفاده از Reflection است که در زمینهی ارائهی برنامههایی با کارآیی بالا و با مصرف حافظهی پایین، بهینه عمل نمیکند. راهحل جایگزین استفاده از Reflection که در زمان اجرای برنامه رخ میدهد، به همراه دات نت 5 ارائه شد و source generators نام دارد. Source generators امکان تولید فایلهای #C را در زمان کامپایل برنامه میسر میکنند که نسبت به راهحل Reflection که در زمان اجرای برنامه فعال میشود، کارآیی بسیار بیشتری را ارائه میکنند. برای مثال به همراه دات نت 6، علاوه بر روش پیشفرض مبتنی بر Reflection ارائه شدهی توسط System.Text.Json، راه حل جدید امکان استفادهی از source generators توکار آن نیز پیش بینی شدهاست. کار اصلی آن، انجام تمام مراحلی است که پیشتر توسط Reflection در زمان اجرای برنامه صورت میگرفت، اینبار در زمان کامپایل برنامه و ارائهی آن به صورت از پیش آماده شده و مهیا.
مزایای این روش شامل موارد زیر است:
- بالا رفتن سرعت برنامه
- کاهش زمان آغاز اولیهی برنامه
- کاهش میزان حافظهی مورد نیاز برنامه
- عدم نیاز به استفادهی از System.Reflection و System.Reflection.Emit
- ارائهی Trim-compatible serialization که سبب کاهش اندازهی نهایی برنامه میشود. برای مثال در برنامههای Blazor میتوان با فعالسازی Trimming، کدهای استفاده نشده را از فایلهای بایناری نهایی حذف کرد. استفاده از source generators، با این روش سازگاری کاملی دارد.
مثالی از نحوهی کار با JSON در دات نت 6، توسط source generators آن
فرض کنید قصد داریم اعمال serialization و deserialization از نوع JSON را بر روی نمونههای کلاس زیر انجام دهیم:
namespace Test { internal class Person { public string FirstName { get; set; } public string LastName { get; set; } } }
using System.Text.Json.Serialization; namespace Test { [JsonSerializable(typeof(Person))] internal partial class MyJsonContext : JsonSerializerContext { } }
پس از آن فقط کافی است MyJsonContext را به عنوان پارامتر متدهای جدید Serialize و یا Deserialize، به صورت زیر ارسال کنیم تا از آن استفاده شود:
Person person = new() { FirstName = "Jane", LastName = "Doe" }; byte[] utf8Json = JsonSerializer.SerializeToUtf8Bytes(person, MyJsonContext.Default.Person); person = JsonSerializer.Deserialize(utf8Json, MyJsonContext.Default.Person);
متدهای جدید این API مبتنی بر source generators را در ادامه ملاحظه میکنید:
namespace System.Text.Json { public static class JsonSerializer { public static object? Deserialize(ReadOnlySpan<byte> utf8Json, Type returnType, JsonSerializerContext context) => ...; public static object? Deserialize(ReadOnlySpan<char> json, Type returnType, JsonSerializerContext context) => ...; public static object? Deserialize(string json, Type returnType, JsonSerializerContext context) => ...; public static object? Deserialize(ref Utf8JsonReader reader, Type returnType, JsonSerializerContext context) => ...; public static ValueTask<object?> DeserializeAsync(Stream utf8Json, Type returnType, JsonSerializerContext context, CancellationToken cancellationToken = default(CancellationToken)) => ...; public static ValueTask<TValue?> DeserializeAsync<TValue>(Stream utf8Json, JsonTypeInfo<TValue> jsonTypeInfo, CancellationToken cancellationToken = default(CancellationToken)) => ...; public static TValue? Deserialize<TValue>(ReadOnlySpan<byte> utf8Json, JsonTypeInfo<TValue> jsonTypeInfo) => ...; public static TValue? Deserialize<TValue>(string json, JsonTypeInfo<TValue> jsonTypeInfo) => ...; public static TValue? Deserialize<TValue>(ReadOnlySpan<char> json, JsonTypeInfo<TValue> jsonTypeInfo) => ...; public static TValue? Deserialize<TValue>(ref Utf8JsonReader reader, JsonTypeInfo<TValue> jsonTypeInfo) => ...; public static string Serialize(object? value, Type inputType, JsonSerializerContext context) => ...; public static void Serialize(Utf8JsonWriter writer, object? value, Type inputType, JsonSerializerContext context) { } public static Task SerializeAsync(Stream utf8Json, object? value, Type inputType, JsonSerializerContext context, CancellationToken cancellationToken = default(CancellationToken)) => ...; public static Task SerializeAsync<TValue>(Stream utf8Json, TValue value, JsonTypeInfo<TValue> jsonTypeInfo, CancellationToken cancellationToken = default(CancellationToken)) => ...; public static byte[] SerializeToUtf8Bytes(object? value, Type inputType, JsonSerializerContext context) => ...; public static byte[] SerializeToUtf8Bytes<TValue>(TValue value, JsonTypeInfo<TValue> jsonTypeInfo) => ...; public static void Serialize<TValue>(Utf8JsonWriter writer, TValue value, JsonTypeInfo<TValue> jsonTypeInfo) { } public static string Serialize<TValue>(TValue value, JsonTypeInfo<TValue> jsonTypeInfo) => ...; } }
برای معرفی تنظیمات serialization و deserialization، برای مثال تهیهی خروجیهای CamelCase، میتوان از ویژگی JsonSourceGenerationOptions به صورت زیر استفاده کرد:
using System.Text.Json.Serialization; namespace Test { [JsonSourceGenerationOptions(PropertyNamingPolicy = JsonKnownNamingPolicy.CamelCase)] [JsonSerializable(typeof(Person))] internal partial class MyJsonContext : JsonSerializerContext { } }
string json = JsonSerializer.Serialize(person, MyJsonContext.Default.Person); Person person = JsonSerializer.Deserialize(json, MyJsonContext.Default.Person);
روش استفاده از JSON Source generators در برنامههای ASP.NET Core
در این نوع برنامهها، JsonSerializerContextها را میتوان توسط متد AddContext به صورت زیر به تنظیمات JSON برنامه معرفی کرد:
services.AddControllers().AddJsonOptions(options => options.AddContext<MyJsonContext>());
روش استفاده از JSON Source generators در برنامههای Blazor
البته در اینجا بیشتر منظور امکان استفادهی از آنها توسط HttpClient است که به صورت زیر توسط متد GetFromJsonAsync واقع در فضای نام System.Net.Http.Json، میسر شدهاست:
[JsonSerializable(typeof(WeatherForecast[]))] internal partial class MyJsonContext : JsonSerializerContext { } @code { private WeatherForecast[] forecasts; private static JsonSerializerOptions Options = new(JsonSerializerDefaults.Web); private static MyJsonContext Context = new MyJsonContext(Options); protected override async Task OnInitializedAsync() { forecasts = await Http.GetFromJsonAsync("sample-data/weather.json", Context.WeatherForecastArray); } }
namespace System.Net.Http.Json { public static partial class HttpClientJsonExtensions { public static Task<object?> GetFromJsonAsync(this HttpClient client, string? requestUri, Type type, JsonSerializerContext context, CancellationToken cancellationToken = default(CancellationToken)) => ...; public static Task<object?> GetFromJsonAsync(this HttpClient client, System.Uri? requestUri, Type type, JsonSerializerContext context, CancellationToken cancellationToken = default(CancellationToken)) => ...; public static Task<TValue?> GetFromJsonAsync<TValue>(this HttpClient client, string? requestUri, JsonTypeInfo<TValue> jsonTypeInfo, CancellationToken cancellationToken = default(CancellationToken)) => ...; public static Task<TValue?> GetFromJsonAsync<TValue>(this HttpClient client, System.Uri? requestUri, JsonTypeInfo<TValue> jsonTypeInfo, CancellationToken cancellationToken = default(CancellationToken)) => ...; public static Task<HttpResponseMessage> PostAsJsonAsync<TValue>(this HttpClient client, string? requestUri, TValue value, JsonTypeInfo<TValue> jsonTypeInfo, CancellationToken cancellationToken = default(CancellationToken)) => ...; public static Task<HttpResponseMessage> PostAsJsonAsync<TValue>(this HttpClient client, System.Uri? requestUri, TValue value, JsonTypeInfo<TValue> jsonTypeInfo, CancellationToken cancellationToken = default(CancellationToken)) => ...; public static Task<HttpResponseMessage> PutAsJsonAsync<TValue>(this HttpClient client, string? requestUri, TValue value, JsonTypeInfo<TValue> jsonTypeInfo, CancellationToken cancellationToken = default(CancellationToken)) => ...; public static Task<HttpResponseMessage> PutAsJsonAsync<TValue>(this HttpClient client, System.Uri? requestUri, TValue value, JsonTypeInfo<TValue> jsonTypeInfo, CancellationToken cancellationToken = default(CancellationToken)) => ...; } public static partial class HttpContentJsonExtensions { public static Task<object?> ReadFromJsonAsync(this HttpContent content, Type type, JsonSerializerContext context, CancellationToken cancellationToken = default(CancellationToken)) => ...; public static Task<T?> ReadFromJsonAsync<T>(this HttpContent content, JsonTypeInfo<TValue> jsonTypeInfo, CancellationToken cancellationToken = default(CancellationToken)) => ...; } }
HttpClient به عنوان جایگزینی برای HttpWebRequest API قدیمی، به همراه NET 4.5. ارائه شد و هدف آن یکپارچه کردن پیاده سازیهای متفاوت موجود به همراه ارائه راهحلی چندسکویی است که از WPF/UWP ، ASP.NET تا NET Core. و iOS/Android را نیز پشتیبانی میکند. تمام قابلیتهای جدید پروتکل HTTP مانند HTTP/2 نیز از این پس تنها به همراه این API ارائه میشوند.
در مطلب «روش استفادهی صحیح از HttpClient در برنامههای دات نت» با روش استفادهی تک وهلهای آن آشنا شدیم. در این مطلب نکات ویژهی دریافت فایلهای حجیم آنرا بررسی خواهیم کرد. بدون توجه به این نکات، یا OutOfMemoryException را دریافت خواهید کرد و یا پیش از پایان کار، با خطای Timeout این پروسه به پایان خواهد رسید.
مشکل اول: نیاز به تغییر Timeout پیش فرض
فرض کنید میخواهیم فایل حجیمی را با تنظیمات پیشفرض HttpClient دریافت کنیم:
در این حالت باتوجه به اینکه Timeout پیشفرض HttpClient به 100 ثانیه تنظیم شدهاست، اگر سرعت دریافت بالایی را نداشته باشید و نتوانید این فایل را پیش از 2 دقیقه دریافت کنید، برنامه با استثنای TaskCancelledException متوقف خواهد شد.
بنابراین اولین تغییر مورد نیاز، تنظیم صریح Timeout آن است:
مشکل دوم: دریافت استثنای OutOfMemoryExceptions
روش دریافت پیشفرض اطلاعات توسط HttpClient، نگهداری و بافر تمام آنها در حافظهی سیستم است. این روش برای اطلاعات کم حجم، مشکلی را به همراه نخواهد داشت. بنابراین در حین دریافت فایلهای چندگیگابایتی با آن، حتما با استثنای OutOfMemoryException مواجه خواهیم شد.
در این حالت برای رفع مشکل، از متد ReadAsStreamAsync آن استفاده میکنیم. به این ترتیب بجای یک آرایهی بزرگ از بایتها، با استریمی از آنها سر و کار داشته و به این صورت مشکل مواجه شدن با کمبود حافظه برطرف میشود.
مشکل: در این حالت اگر برنامه را اجرا کنید، تا پایان کار متد DownloadLargeFileAsync، حجم فایل دریافتی تغییری نخواهد کرد. یعنی هنوز هم کل فایل در حافظه بافر میشود و سپس استریم آن در اختیار FileStream نهایی برای نوشتن قرار خواهد گرفت.
علت اینجا است که متد client.GetAsync تا زمانیکه کل Response ارسالی از طرف سرور خوانده نشود (headers + content)، عملیات را سد کرده و منتظر میماند. بنابراین با این تغییرات عملا به نتیجهی دلخواه نرسیدهایم.
دریافت اطلاعات Header و سپس استریم کردن Content
چون متد client.GetAsync تا دریافت کامل headers + content متوقف میماند، میتوان به آن اعلام کرد تنها هدر را به صورت کامل دریافت کن و سپس باقیماندهی عملیات دریافت بدنهی Response را به صورت Stream در اختیار ادامهی برنامه قرار بده. برای اینکار نیاز است پارامتر HttpCompletionOption را تکمیل کرد:
پارامتر HttpCompletionOption.ResponseHeadersRead به متد GetAsync اعلام میکند که پس از خواندن هدر Response، ادامهی عملیات را در اختیار سطرهای بعدی کد قرار بده و عملیات را تا پایان خواندن کامل Response در حافظه، متوقف نکن.
مشکل سوم: برنامه در دریافت سومین فایل از یک سرور هنگ میکند.
تعداد اتصالات همزمانی را که میتوان توسط HttpClient به یک سرور گشود، محدود هستند. برای مثال این عدد در Full .NET Framework مساوی 2 است. بنابراین اگر اتصال سوم موازی را شروع کنیم، چون Timeout را به بینهایت تنظیم کردهایم، این قسمت از برنامه هیچگاه تکمیل نخواهد شد.
روش تنظیم تعداد اتصالات مجاز به یک سرور:
- در Full .NET Framework با تنظیم خاصیت ServicePointManager.DefaultConnectionLimit است که به 2 تنظیم شدهاست.
- این مورد در NET Core. توسط پارامتر HttpClientHandler و خاصیت MaxConnectionsPerServer آن تنظیم میشود:
البته مقدار پیشفرض آن int.MaxValue است که نسبت به حالت Full .NET Framework عدد بسیار بزرگتری است.
در مطلب «روش استفادهی صحیح از HttpClient در برنامههای دات نت» با روش استفادهی تک وهلهای آن آشنا شدیم. در این مطلب نکات ویژهی دریافت فایلهای حجیم آنرا بررسی خواهیم کرد. بدون توجه به این نکات، یا OutOfMemoryException را دریافت خواهید کرد و یا پیش از پایان کار، با خطای Timeout این پروسه به پایان خواهد رسید.
مشکل اول: نیاز به تغییر Timeout پیش فرض
فرض کنید میخواهیم فایل حجیمی را با تنظیمات پیشفرض HttpClient دریافت کنیم:
using System; using System.Net.Http; using System.Threading.Tasks; namespace HttpClientTips.LargeFiles { class Program { private static readonly HttpClient _client = new HttpClient(); static async Task Main(string[] args) { var bytes = await DownloadLargeFileAsync(); } public static async Task<byte[]> DownloadLargeFileAsync() { Console.WriteLine("Downloading a 4K content - too much bytes."); var response = await _client.GetAsync("http://downloads.4ksamples.com/downloads/sample-Elysium.2013.2160p.mkv"); var bytes = await response.Content.ReadAsByteArrayAsync(); return bytes; } } }
بنابراین اولین تغییر مورد نیاز، تنظیم صریح Timeout آن است:
private static readonly HttpClient _client = new HttpClient { Timeout = Timeout.InfiniteTimeSpan };
مشکل دوم: دریافت استثنای OutOfMemoryExceptions
روش دریافت پیشفرض اطلاعات توسط HttpClient، نگهداری و بافر تمام آنها در حافظهی سیستم است. این روش برای اطلاعات کم حجم، مشکلی را به همراه نخواهد داشت. بنابراین در حین دریافت فایلهای چندگیگابایتی با آن، حتما با استثنای OutOfMemoryException مواجه خواهیم شد.
namespace HttpClientTips.LargeFiles { class Program { private static readonly HttpClient _client = new HttpClient { Timeout = Timeout.InfiniteTimeSpan }; static async Task Main(string[] args) { await DownloadLargeFileAsync(); } public static async Task DownloadLargeFileAsync() { Console.WriteLine("Downloading a 4K content. too much bytes."); var response = await _client.GetAsync("http://downloads.4ksamples.com/downloads/sample-Elysium.2013.2160p.mkv"); using (var streamToReadFrom = await response.Content.ReadAsStreamAsync()) { string fileToWriteTo = Path.GetTempFileName(); Console.WriteLine($"Save path: {fileToWriteTo}"); using (var streamToWriteTo = File.Open(fileToWriteTo, FileMode.Create)) { await streamToReadFrom.CopyToAsync(streamToWriteTo); } } } } }
مشکل: در این حالت اگر برنامه را اجرا کنید، تا پایان کار متد DownloadLargeFileAsync، حجم فایل دریافتی تغییری نخواهد کرد. یعنی هنوز هم کل فایل در حافظه بافر میشود و سپس استریم آن در اختیار FileStream نهایی برای نوشتن قرار خواهد گرفت.
علت اینجا است که متد client.GetAsync تا زمانیکه کل Response ارسالی از طرف سرور خوانده نشود (headers + content)، عملیات را سد کرده و منتظر میماند. بنابراین با این تغییرات عملا به نتیجهی دلخواه نرسیدهایم.
دریافت اطلاعات Header و سپس استریم کردن Content
چون متد client.GetAsync تا دریافت کامل headers + content متوقف میماند، میتوان به آن اعلام کرد تنها هدر را به صورت کامل دریافت کن و سپس باقیماندهی عملیات دریافت بدنهی Response را به صورت Stream در اختیار ادامهی برنامه قرار بده. برای اینکار نیاز است پارامتر HttpCompletionOption را تکمیل کرد:
var response = await _client.GetAsync( "http://downloads.4ksamples.com/downloads/sample-Elysium.2013.2160p.mkv", HttpCompletionOption.ResponseHeadersRead);
مشکل سوم: برنامه در دریافت سومین فایل از یک سرور هنگ میکند.
تعداد اتصالات همزمانی را که میتوان توسط HttpClient به یک سرور گشود، محدود هستند. برای مثال این عدد در Full .NET Framework مساوی 2 است. بنابراین اگر اتصال سوم موازی را شروع کنیم، چون Timeout را به بینهایت تنظیم کردهایم، این قسمت از برنامه هیچگاه تکمیل نخواهد شد.
روش تنظیم تعداد اتصالات مجاز به یک سرور:
- در Full .NET Framework با تنظیم خاصیت ServicePointManager.DefaultConnectionLimit است که به 2 تنظیم شدهاست.
- این مورد در NET Core. توسط پارامتر HttpClientHandler و خاصیت MaxConnectionsPerServer آن تنظیم میشود:
private static readonly HttpClientHandler _handler = new HttpClientHandler { MaxConnectionsPerServer = int.MaxValue, // default for .NET Core UseDefaultCredentials = true }; private static readonly HttpClient _client = new HttpClient(_handler) { Timeout = Timeout.InfiniteTimeSpan };
AuthenticationMiddleware در ASP.NET Core 2.0، فقط مختص به کار با کوکیها جهت اعتبارسنجی کاربران نیست. از این میانافزار میتوان برای اعتبار سنجیهای مبتنی بر JSON Web Tokens نیز استفاده کرد. مطلبی را که در ادامه مطالعه خواهید کرد دقیقا بر اساس نکات مطلب «پیاده سازی JSON Web Token با ASP.NET Web API 2.x» تدارک دیده شدهاست و به همراه نکاتی مانند تولید Refresh Tokens و یا غیرمعتبر سازی توکنها نیز هست. همچنین ساختار جداول کاربران و نقشهای آنها، سرویسهای مرتبط و قسمت تنظیمات Context آن با مطلب «اعتبارسنجی مبتنی بر کوکیها در ASP.NET Core 2.0 بدون استفاده از سیستم Identity» یکی است. در اینجا بیشتر به تفاوتهای پیاده سازی این روش نسبت به حالت اعتبارسنجی مبتنی بر کوکیها خواهیم پرداخت.
همچنین باید درنظر داشت، ASP.NET Core Identity یک سیستم اعتبارسنجی مبتنی بر کوکیها است. دقیقا زمانیکه کار AddIdentity را انجام میدهیم، در پشت صحنه همان services.AddAuthentication().AddCookie قسمت قبل فراخوانی میشود. بنابراین بکارگیری آن با JSON Web Tokens هرچند مشکلی را به همراه ندارد و میتوان یک سیستم اعتبارسنجی «دوگانه» را نیز در اینجا داشت، اما ... سربار اضافی تولید کوکیها را نیز به همراه دارد؛ هرچند برای کار با میانافزار اعتبارسنجی، الزامی به استفادهی از ASP.NET Core Identity نیست و عموما اگر از آن به همراه JWT استفاده میکنند، بیشتر به دنبال پیاده سازیهای پیشفرض مدیریت کاربران و نقشهای آن هستند و نه قسمت تولید کوکیهای آن. البته در مطلب جاری این موارد را نیز همانند مطلب اعتبارسنجی مبتنی بر کوکیها، خودمان مدیریت خواهیم کرد و در نهایت سیستم تهیه شده، هیچ نوع کوکی را تولید و یا مدیریت نمیکند.
تنظیمات آغازین برنامه جهت فعالسازی اعتبارسنجی مبتنی بر JSON Web Tokens
اولین تفاوت پیاده سازی یک سیستم اعتبارسنجی مبتنی بر JWT، با روش مبتنی بر کوکیها، تنظیمات متد ConfigureServices فایل آغازین برنامه است:
در اینجا در ابتدا تنظیمات JWT فایل appsettings.json
به کلاسی دقیقا با همین ساختار به نام BearerTokensOptions، نگاشت شدهاند. به این ترتیب میتوان با تزریق اینترفیس <IOptionsSnapshot<BearerTokensOptions در قسمتهای مختلف برنامه، به این تنظیمات مانند کلید رمزنگاری، مشخصات صادر کننده، مخاطبین و طول عمرهای توکنهای صادر شده، دسترسی یافت.
سپس کار فراخوانی services.AddAuthentication صورت گرفتهاست. تفاوت این مورد با حالت اعتبارسنجی مبتنی بر کوکیها، ثوابتی است که با JwtBearerDefaults شروع میشوند. در حالت استفادهی از کوکیها، این ثوابت بر اساس CookieAuthenticationDefaults تنظیم خواهند شد.
البته میتوان متد AddAuthentication را بدون هیچگونه پارامتری نیز فراخوانی کرد. این حالت برای اعتبارسنجیهای دوگانه مفید است. برای مثال زمانیکه پس از AddAuthentication هم AddJwtBearer را ذکر کردهاید و هم AddCookie اضافه شدهاست. اگر چنین کاری را انجام دادید، اینبار باید درحین تعریف فیلتر Authorize، دقیقا مشخص کنید که حالت مبتنی بر JWT مدنظر شما است، یا حالت مبتنی بر کوکیها:
اگر متد AddAuthentication، مانند تنظیمات فوق به همراه این تنظیمات پیشفرض بود، دیگر نیازی به ذکر صریح AuthenticationSchemes در فیلتر Authorize نخواهد بود.
بررسی تنظیمات متد AddJwtBearer
در کدهای فوق، تنظیمات متد AddJwtBearer یک چنین مفاهیمی را به همراه دارند:
- تنظیم SaveToken به true، به این معنا است که میتوان به توکن دریافتی از سمت کاربر، توسط متد HttpContext.GetTokenAsync در کنترلرهای برنامه دسترسی یافت.
در قسمت تنظیمات TokenValidationParameters آن:
- کار خواندن فایل appsettings.json برنامه جهت تنظیم صادر کننده و مخاطبین توکن انجام میشود. سپس IssuerSigningKey به یک کلید رمزنگاری متقارن تنظیم خواهد شد. این کلید نیز در تنظیمات برنامه قید میشود.
- تنظیم ValidateIssuerSigningKey به true سبب خواهد شد تا میانافزار اعتبارسنجی، بررسی کند که آیا توکن دریافتی از سمت کاربر توسط برنامهی ما امضاء شدهاست یا خیر؟
- تنظیم ValidateLifetime به معنای بررسی خودکار طول عمر توکن دریافتی از سمت کاربر است. اگر توکن منقضی شده باشد، اعتبارسنجی به صورت خودکار خاتمه خواهد یافت.
- ClockSkew به معنای تنظیم یک تلرانس و حد تحمل مدت زمان منقضی شدن توکن در حالت ValidateLifetime است. در اینجا به صفر تنظیم شدهاست.
سپس به قسمت JwtBearerEvents میرسیم:
- OnAuthenticationFailed زمانی فراخوانی میشود که اعتبارسنجهای تنظیمی فوق، با شکست مواجه شوند. برای مثال طول عمر توکن منقضی شده باشد و یا توسط ما امضاء نشدهباشد. در اینجا میتوان به این خطاها دسترسی یافت و درصورت نیاز آنها را لاگ کرد.
- OnChallenge نیز یک سری دیگر از خطاهای اعتبارسنجی را پیش از ارسال آنها به فراخوان در اختیار ما قرار میدهد.
- OnMessageReceived برای حالتی است که توکن دریافتی، توسط هدر مخصوص Bearer به سمت سرور ارسال نمیشود. عموما هدر ارسالی به سمت سرور یک چنین شکلی را دارد:
اما اگر توکن شما به این شکل استاندارد دریافت نمیشود، میتوان در رخداد OnMessageReceived به اطلاعات درخواست جاری دسترسی یافت، توکن را از آن استخراج کرد و سپس آنرا به خاصیت context.Token انتساب داد، تا به عنوان توکن اصلی مورد استفاده قرار گیرد. برای مثال:
- OnTokenValidated پس از کامل شدن اعتبارسنجی توکن دریافتی از سمت کاربر فراخوانی میشود. در اینجا اگر متد context.Fail را فراخوانی کنیم، این توکن، به عنوان یک توکن غیرمعتبر علامتگذاری میشود و عملیات اعتبارسنجی با شکست خاتمه خواهد یافت. بنابراین میتوان از آن دقیقا مانند CookieValidatorService قسمت قبل که جهت واکنش نشان دادن به تغییرات اطلاعات کاربر در سمت سرور مورد استفاده قرار دادیم، در اینجا نیز یک چنین منطقی را پیاده سازی کنیم.
تهیه یک اعتبارسنج توکن سفارشی
قسمت OnTokenValidated تنظیمات ابتدای برنامه به این صورت مقدار دهی شدهاست:
TokenValidatorService سفارشی ما چنین پیاده سازی را دارد:
در اینجا بررسی میکنیم:
- آیا توکن دریافتی به همراه Claims تنظیم شدهی درحین لاگین هست یا خیر؟
- آیا توکن دریافتی دارای یک Claim سفارشی به نام SerialNumber است؟ این SerialNumber معادل چنین فیلدی در جدول کاربران است.
- آیا توکن دریافتی دارای user-id است؟
- آیا کاربر یافت شدهی بر اساس این user-id هنوز فعال است و یا اطلاعات او تغییر نکردهاست؟
- همچنین در آخر کار بررسی میکنیم که آیا اصل توکن دریافتی، در بانک اطلاعاتی ما پیشتر ثبت شدهاست یا خیر؟
اگر خیر، بلافاصله متد context.Fail فراخوانی شده و کار اعتبارسنجی را با اعلام شکست آن، به پایان میرسانیم.
در قسمت آخر، نیاز است اطلاعات توکنهای صادر شده را ذخیره کنیم. به همین جهت نسبت به مطلب قبلی، جدول UserToken ذیل به برنامه اضافه شدهاست:
در اینجا هشهای توکنهای صادر شدهی توسط برنامه و طول عمر آنها را ذخیره خواهیم کرد.
از اطلاعات آن در دو قسمت TokenValidatorService فوق و همچنین قسمت logout برنامه استفاده میکنیم. در سیستم JWT، مفهوم logout سمت سرور وجود خارجی ندارد. اما با ذخیره سازی هش توکنها در بانک اطلاعاتی میتوان لیستی از توکنهای صادر شدهی توسط برنامه را تدارک دید. سپس در حین logout فقط کافی است tokenهای یک کاربر را حذف کرد. همینقدر سبب خواهد شد تا قسمت آخر TokenValidatorService با شکست مواجه شود؛ چون توکن ارسالی به سمت سرور دیگر در بانک اطلاعاتی وجود ندارد.
سرویس TokenStore
در قسمت آخر اعتبارسنج سفارشی توکن، بررسی وجود توکن دریافتی، توسط سرویس TokenStore فوق صورت میگیرد. از این سرویس برای تولید، ذخیره سازی و حذف توکنها استفاده خواهیم کرد.
پیاده سازی کامل این سرویس را در اینجا میتوانید مشاهده کنید.
تولید Access Tokens و Refresh Tokens
پس از تنظیمات ابتدایی برنامه، اکنون میتوانیم دو نوع توکن را تولید کنیم:
تولید Access Tokens
این امکانات در اسمبلی زیر قرار دارند:
در اینجا ابتدا همانند کار با سیستم اعتبارسنجی مبتنی بر کوکیها، نیاز است یک سری Claim تهیه شوند. به همین جهت SerialNumber، UserId و همچنین نقشهای کاربر لاگین شدهی به سیستم را در اینجا به مجموعهی Claims اضافه میکنیم. وجود این Claims است که سبب میشود فیلتر Authorize بتواند نقشها را تشخیص داده و یا کاربر را اعتبارسنجی کند.
پس از تهیهی Claims، اینبار بجای یک کوکی، یک JSON Web Toekn را توسط متد new JwtSecurityTokenHandler().WriteToken تهیه خواهیم کرد. این توکن حاوی Claims، به همراه اطلاعات طول عمر و امضای مرتبطی است.
حاصل آن نیز یک رشتهاست که دقیقا به همین فرمت به سمت کلاینت ارسال خواهد شد. البته ما در اینجا دو نوع توکن را به سمت کلاینت ارسال میکنیم:
accessToken همان JSON Web Token اصلی است. refreshToken فقط یک Guid است. کار آن ساده سازی و به روز رسانی عملیات Login بدون ارائهی نام کاربری و کلمهی عبور است. به همین جهت است که نیاز داریم تا این اطلاعات را در سمت بانک اطلاعاتی برنامه نیز ذخیره کنیم. فرآیند اعتبارسنجی یک refreshToken بدون ذخیره سازی این Guid در بانک اطلاعاتی مسیر نیست که در اینجا در فیلد RefreshTokenIdHash جدول UserToken ذخیره میشود.
جهت بالا رفتن امنیت سیستم، این Guid را هش کرد و سپس این هش را در بانک اطلاعاتی ذخیره میکنیم. به این ترتیب دسترسی غیرمجاز به این هشها، امکان بازیابی توکنهای اصلی را غیرممکن میکند.
پیاده سازی Login
پس از پیاده سازی متد CreateJwtTokens، کار ورود به سیستم به سادگی ذیل خواهد بود:
ابتدا بررسی میشود که آیا کلمهی عبور و نام کاربری وارد شده صحیح هستند یا خیر و آیا کاربر متناظر با آن هنوز فعال است. اگر بله، دو توکن دسترسی و به روز رسانی را تولید و به سمت کلاینت ارسال میکنیم.
پیاده سازی Refresh Token
پیاده سازی توکن به روز رسانی همانند عملیات لاگین است:
با این تفاوت که در اینجا فقط یک Guid از سمت کاربر دریافت شده، سپس بر اساس این Guid، توکن و کاربر متناظر با آن یافت میشوند. سپس یک توکن جدید را بر اساس این اطلاعات تولید کرده و به سمت کاربر ارسال میکنیم.
پیاده سازی Logout
در سیستمهای مبتنی بر JWT، پیاده سازی Logout سمت سرور بیمفهوم است؛ از این جهت که تا زمان انقضای یک توکن میتوان از آن توکن جهت ورود به سیستم و دسترسی به منابع آن استفاده کرد. بنابراین تنها راه پیاده سازی Logout، ذخیره سازی توکنها در بانک اطلاعاتی و سپس حذف آنها در حین خروج از سیستم است. به این ترتیب اعتبارسنج سفارشی توکنها، از استفادهی مجدد از توکنی که هنوز هم معتبر است و منقضی نشدهاست، جلوگیری خواهد کرد:
آزمایش نهایی برنامه
در فایل index.html، نمونهای از متدهای لاگین، خروج و فراخوانی اکشن متدهای محافظت شده را مشاهده میکنید. این روش برای برنامههای تک صفحهای وب یا SPA نیز میتواند مفید باشد و به همین نحو کار میکنند.
کدهای کامل این مطلب را از اینجا میتوانید دریافت کنید.
همچنین باید درنظر داشت، ASP.NET Core Identity یک سیستم اعتبارسنجی مبتنی بر کوکیها است. دقیقا زمانیکه کار AddIdentity را انجام میدهیم، در پشت صحنه همان services.AddAuthentication().AddCookie قسمت قبل فراخوانی میشود. بنابراین بکارگیری آن با JSON Web Tokens هرچند مشکلی را به همراه ندارد و میتوان یک سیستم اعتبارسنجی «دوگانه» را نیز در اینجا داشت، اما ... سربار اضافی تولید کوکیها را نیز به همراه دارد؛ هرچند برای کار با میانافزار اعتبارسنجی، الزامی به استفادهی از ASP.NET Core Identity نیست و عموما اگر از آن به همراه JWT استفاده میکنند، بیشتر به دنبال پیاده سازیهای پیشفرض مدیریت کاربران و نقشهای آن هستند و نه قسمت تولید کوکیهای آن. البته در مطلب جاری این موارد را نیز همانند مطلب اعتبارسنجی مبتنی بر کوکیها، خودمان مدیریت خواهیم کرد و در نهایت سیستم تهیه شده، هیچ نوع کوکی را تولید و یا مدیریت نمیکند.
تنظیمات آغازین برنامه جهت فعالسازی اعتبارسنجی مبتنی بر JSON Web Tokens
اولین تفاوت پیاده سازی یک سیستم اعتبارسنجی مبتنی بر JWT، با روش مبتنی بر کوکیها، تنظیمات متد ConfigureServices فایل آغازین برنامه است:
public void ConfigureServices(IServiceCollection services) { services.Configure<BearerTokensOptions>(options => Configuration.GetSection("BearerTokens").Bind(options)); services .AddAuthentication(options => { options.DefaultChallengeScheme = JwtBearerDefaults.AuthenticationScheme; options.DefaultSignInScheme = JwtBearerDefaults.AuthenticationScheme; options.DefaultAuthenticateScheme = JwtBearerDefaults.AuthenticationScheme; }) .AddJwtBearer(cfg => { cfg.RequireHttpsMetadata = false; cfg.SaveToken = true; cfg.TokenValidationParameters = new TokenValidationParameters { ValidIssuer = Configuration["BearerTokens:Issuer"], ValidAudience = Configuration["BearerTokens:Audience"], IssuerSigningKey = new SymmetricSecurityKey(Encoding.UTF8.GetBytes(Configuration["BearerTokens:Key"])), ValidateIssuerSigningKey = true, ValidateLifetime = true, ClockSkew = TimeSpan.Zero }; cfg.Events = new JwtBearerEvents { OnAuthenticationFailed = context => { var logger = context.HttpContext.RequestServices.GetRequiredService<ILoggerFactory>().CreateLogger(nameof(JwtBearerEvents)); logger.LogError("Authentication failed.", context.Exception); return Task.CompletedTask; }, OnTokenValidated = context => { var tokenValidatorService = context.HttpContext.RequestServices.GetRequiredService<ITokenValidatorService>(); return tokenValidatorService.ValidateAsync(context); }, OnMessageReceived = context => { return Task.CompletedTask; }, OnChallenge = context => { var logger = context.HttpContext.RequestServices.GetRequiredService<ILoggerFactory>().CreateLogger(nameof(JwtBearerEvents)); logger.LogError("OnChallenge error", context.Error, context.ErrorDescription); return Task.CompletedTask; } }; });
{ "BearerTokens": { "Key": "This is my shared key, not so secret, secret!", "Issuer": "http://localhost/", "Audience": "Any", "AccessTokenExpirationMinutes": 2, "RefreshTokenExpirationMinutes": 60 } }
سپس کار فراخوانی services.AddAuthentication صورت گرفتهاست. تفاوت این مورد با حالت اعتبارسنجی مبتنی بر کوکیها، ثوابتی است که با JwtBearerDefaults شروع میشوند. در حالت استفادهی از کوکیها، این ثوابت بر اساس CookieAuthenticationDefaults تنظیم خواهند شد.
البته میتوان متد AddAuthentication را بدون هیچگونه پارامتری نیز فراخوانی کرد. این حالت برای اعتبارسنجیهای دوگانه مفید است. برای مثال زمانیکه پس از AddAuthentication هم AddJwtBearer را ذکر کردهاید و هم AddCookie اضافه شدهاست. اگر چنین کاری را انجام دادید، اینبار باید درحین تعریف فیلتر Authorize، دقیقا مشخص کنید که حالت مبتنی بر JWT مدنظر شما است، یا حالت مبتنی بر کوکیها:
[Authorize(AuthenticationSchemes = JwtBearerDefaults.AuthenticationScheme)]
بررسی تنظیمات متد AddJwtBearer
در کدهای فوق، تنظیمات متد AddJwtBearer یک چنین مفاهیمی را به همراه دارند:
- تنظیم SaveToken به true، به این معنا است که میتوان به توکن دریافتی از سمت کاربر، توسط متد HttpContext.GetTokenAsync در کنترلرهای برنامه دسترسی یافت.
در قسمت تنظیمات TokenValidationParameters آن:
- کار خواندن فایل appsettings.json برنامه جهت تنظیم صادر کننده و مخاطبین توکن انجام میشود. سپس IssuerSigningKey به یک کلید رمزنگاری متقارن تنظیم خواهد شد. این کلید نیز در تنظیمات برنامه قید میشود.
- تنظیم ValidateIssuerSigningKey به true سبب خواهد شد تا میانافزار اعتبارسنجی، بررسی کند که آیا توکن دریافتی از سمت کاربر توسط برنامهی ما امضاء شدهاست یا خیر؟
- تنظیم ValidateLifetime به معنای بررسی خودکار طول عمر توکن دریافتی از سمت کاربر است. اگر توکن منقضی شده باشد، اعتبارسنجی به صورت خودکار خاتمه خواهد یافت.
- ClockSkew به معنای تنظیم یک تلرانس و حد تحمل مدت زمان منقضی شدن توکن در حالت ValidateLifetime است. در اینجا به صفر تنظیم شدهاست.
سپس به قسمت JwtBearerEvents میرسیم:
- OnAuthenticationFailed زمانی فراخوانی میشود که اعتبارسنجهای تنظیمی فوق، با شکست مواجه شوند. برای مثال طول عمر توکن منقضی شده باشد و یا توسط ما امضاء نشدهباشد. در اینجا میتوان به این خطاها دسترسی یافت و درصورت نیاز آنها را لاگ کرد.
- OnChallenge نیز یک سری دیگر از خطاهای اعتبارسنجی را پیش از ارسال آنها به فراخوان در اختیار ما قرار میدهد.
- OnMessageReceived برای حالتی است که توکن دریافتی، توسط هدر مخصوص Bearer به سمت سرور ارسال نمیشود. عموما هدر ارسالی به سمت سرور یک چنین شکلی را دارد:
$.ajax({ headers: { 'Authorization': 'Bearer ' + jwtToken },
const string tokenKey = "my.custom.jwt.token.key"; if (context.HttpContext.Items.ContainsKey(tokenKey)) { context.Token = (string)context.HttpContext.Items[tokenKey]; }
تهیه یک اعتبارسنج توکن سفارشی
قسمت OnTokenValidated تنظیمات ابتدای برنامه به این صورت مقدار دهی شدهاست:
OnTokenValidated = context => { var tokenValidatorService = context.HttpContext.RequestServices.GetRequiredService<ITokenValidatorService>(); return tokenValidatorService.ValidateAsync(context); },
public class TokenValidatorService : ITokenValidatorService { private readonly IUsersService _usersService; private readonly ITokenStoreService _tokenStoreService; public TokenValidatorService(IUsersService usersService, ITokenStoreService tokenStoreService) { _usersService = usersService; _usersService.CheckArgumentIsNull(nameof(usersService)); _tokenStoreService = tokenStoreService; _tokenStoreService.CheckArgumentIsNull(nameof(_tokenStoreService)); } public async Task ValidateAsync(TokenValidatedContext context) { var userPrincipal = context.Principal; var claimsIdentity = context.Principal.Identity as ClaimsIdentity; if (claimsIdentity?.Claims == null || !claimsIdentity.Claims.Any()) { context.Fail("This is not our issued token. It has no claims."); return; } var serialNumberClaim = claimsIdentity.FindFirst(ClaimTypes.SerialNumber); if (serialNumberClaim == null) { context.Fail("This is not our issued token. It has no serial."); return; } var userIdString = claimsIdentity.FindFirst(ClaimTypes.UserData).Value; if (!int.TryParse(userIdString, out int userId)) { context.Fail("This is not our issued token. It has no user-id."); return; } var user = await _usersService.FindUserAsync(userId).ConfigureAwait(false); if (user == null || user.SerialNumber != serialNumberClaim.Value || !user.IsActive) { // user has changed his/her password/roles/stat/IsActive context.Fail("This token is expired. Please login again."); } var accessToken = context.SecurityToken as JwtSecurityToken; if (accessToken == null || string.IsNullOrWhiteSpace(accessToken.RawData) || !await _tokenStoreService.IsValidTokenAsync(accessToken.RawData, userId).ConfigureAwait(false)) { context.Fail("This token is not in our database."); return; } await _usersService.UpdateUserLastActivityDateAsync(userId).ConfigureAwait(false); } }
- آیا توکن دریافتی به همراه Claims تنظیم شدهی درحین لاگین هست یا خیر؟
- آیا توکن دریافتی دارای یک Claim سفارشی به نام SerialNumber است؟ این SerialNumber معادل چنین فیلدی در جدول کاربران است.
- آیا توکن دریافتی دارای user-id است؟
- آیا کاربر یافت شدهی بر اساس این user-id هنوز فعال است و یا اطلاعات او تغییر نکردهاست؟
- همچنین در آخر کار بررسی میکنیم که آیا اصل توکن دریافتی، در بانک اطلاعاتی ما پیشتر ثبت شدهاست یا خیر؟
اگر خیر، بلافاصله متد context.Fail فراخوانی شده و کار اعتبارسنجی را با اعلام شکست آن، به پایان میرسانیم.
در قسمت آخر، نیاز است اطلاعات توکنهای صادر شده را ذخیره کنیم. به همین جهت نسبت به مطلب قبلی، جدول UserToken ذیل به برنامه اضافه شدهاست:
public class UserToken { public int Id { get; set; } public string AccessTokenHash { get; set; } public DateTimeOffset AccessTokenExpiresDateTime { get; set; } public string RefreshTokenIdHash { get; set; } public DateTimeOffset RefreshTokenExpiresDateTime { get; set; } public int UserId { get; set; } // one-to-one association public virtual User User { get; set; } }
از اطلاعات آن در دو قسمت TokenValidatorService فوق و همچنین قسمت logout برنامه استفاده میکنیم. در سیستم JWT، مفهوم logout سمت سرور وجود خارجی ندارد. اما با ذخیره سازی هش توکنها در بانک اطلاعاتی میتوان لیستی از توکنهای صادر شدهی توسط برنامه را تدارک دید. سپس در حین logout فقط کافی است tokenهای یک کاربر را حذف کرد. همینقدر سبب خواهد شد تا قسمت آخر TokenValidatorService با شکست مواجه شود؛ چون توکن ارسالی به سمت سرور دیگر در بانک اطلاعاتی وجود ندارد.
سرویس TokenStore
public interface ITokenStoreService { Task AddUserTokenAsync(UserToken userToken); Task AddUserTokenAsync( User user, string refreshToken, string accessToken, DateTimeOffset refreshTokenExpiresDateTime, DateTimeOffset accessTokenExpiresDateTime); Task<bool> IsValidTokenAsync(string accessToken, int userId); Task DeleteExpiredTokensAsync(); Task<UserToken> FindTokenAsync(string refreshToken); Task DeleteTokenAsync(string refreshToken); Task InvalidateUserTokensAsync(int userId); Task<(string accessToken, string refreshToken)> CreateJwtTokens(User user); }
پیاده سازی کامل این سرویس را در اینجا میتوانید مشاهده کنید.
تولید Access Tokens و Refresh Tokens
پس از تنظیمات ابتدایی برنامه، اکنون میتوانیم دو نوع توکن را تولید کنیم:
تولید Access Tokens
private async Task<string> createAccessTokenAsync(User user, DateTime expires) { var claims = new List<Claim> { // Unique Id for all Jwt tokes new Claim(JwtRegisteredClaimNames.Jti, Guid.NewGuid().ToString()), // Issuer new Claim(JwtRegisteredClaimNames.Iss, _configuration.Value.Issuer), // Issued at new Claim(JwtRegisteredClaimNames.Iat, DateTime.UtcNow.ToUnixEpochDate().ToString(), ClaimValueTypes.Integer64), new Claim(ClaimTypes.NameIdentifier, user.Id.ToString()), new Claim(ClaimTypes.Name, user.Username), new Claim("DisplayName", user.DisplayName), // to invalidate the cookie new Claim(ClaimTypes.SerialNumber, user.SerialNumber), // custom data new Claim(ClaimTypes.UserData, user.Id.ToString()) }; // add roles var roles = await _rolesService.FindUserRolesAsync(user.Id).ConfigureAwait(false); foreach (var role in roles) { claims.Add(new Claim(ClaimTypes.Role, role.Name)); } var key = new SymmetricSecurityKey(Encoding.UTF8.GetBytes(_configuration.Value.Key)); var creds = new SigningCredentials(key, SecurityAlgorithms.HmacSha256); var token = new JwtSecurityToken( issuer: _configuration.Value.Issuer, audience: _configuration.Value.Audience, claims: claims, notBefore: DateTime.UtcNow, expires: expires, signingCredentials: creds); return new JwtSecurityTokenHandler().WriteToken(token); }
<ItemGroup> <PackageReference Include="Microsoft.AspNetCore.Authentication.JwtBearer" Version="2.0.0" /> </ItemGroup>
پس از تهیهی Claims، اینبار بجای یک کوکی، یک JSON Web Toekn را توسط متد new JwtSecurityTokenHandler().WriteToken تهیه خواهیم کرد. این توکن حاوی Claims، به همراه اطلاعات طول عمر و امضای مرتبطی است.
حاصل آن نیز یک رشتهاست که دقیقا به همین فرمت به سمت کلاینت ارسال خواهد شد. البته ما در اینجا دو نوع توکن را به سمت کلاینت ارسال میکنیم:
public async Task<(string accessToken, string refreshToken)> CreateJwtTokens(User user) { var now = DateTimeOffset.UtcNow; var accessTokenExpiresDateTime = now.AddMinutes(_configuration.Value.AccessTokenExpirationMinutes); var refreshTokenExpiresDateTime = now.AddMinutes(_configuration.Value.RefreshTokenExpirationMinutes); var accessToken = await createAccessTokenAsync(user, accessTokenExpiresDateTime.UtcDateTime).ConfigureAwait(false); var refreshToken = Guid.NewGuid().ToString().Replace("-", ""); await AddUserTokenAsync(user, refreshToken, accessToken, refreshTokenExpiresDateTime, accessTokenExpiresDateTime).ConfigureAwait(false); await _uow.SaveChangesAsync().ConfigureAwait(false); return (accessToken, refreshToken); }
جهت بالا رفتن امنیت سیستم، این Guid را هش کرد و سپس این هش را در بانک اطلاعاتی ذخیره میکنیم. به این ترتیب دسترسی غیرمجاز به این هشها، امکان بازیابی توکنهای اصلی را غیرممکن میکند.
پیاده سازی Login
پس از پیاده سازی متد CreateJwtTokens، کار ورود به سیستم به سادگی ذیل خواهد بود:
[AllowAnonymous] [HttpPost("[action]")] public async Task<IActionResult> Login([FromBody] User loginUser) { if (loginUser == null) { return BadRequest("user is not set."); } var user = await _usersService.FindUserAsync(loginUser.Username, loginUser.Password).ConfigureAwait(false); if (user == null || !user.IsActive) { return Unauthorized(); } var (accessToken, refreshToken) = await _tokenStoreService.CreateJwtTokens(user).ConfigureAwait(false); return Ok(new { access_token = accessToken, refresh_token = refreshToken }); }
پیاده سازی Refresh Token
پیاده سازی توکن به روز رسانی همانند عملیات لاگین است:
[AllowAnonymous] [HttpPost("[action]")] public async Task<IActionResult> RefreshToken([FromBody]JToken jsonBody) { var refreshToken = jsonBody.Value<string>("refreshToken"); if (string.IsNullOrWhiteSpace(refreshToken)) { return BadRequest("refreshToken is not set."); } var token = await _tokenStoreService.FindTokenAsync(refreshToken); if (token == null) { return Unauthorized(); } var (accessToken, newRefreshToken) = await _tokenStoreService.CreateJwtTokens(token.User).ConfigureAwait(false); return Ok(new { access_token = accessToken, refresh_token = newRefreshToken }); }
پیاده سازی Logout
در سیستمهای مبتنی بر JWT، پیاده سازی Logout سمت سرور بیمفهوم است؛ از این جهت که تا زمان انقضای یک توکن میتوان از آن توکن جهت ورود به سیستم و دسترسی به منابع آن استفاده کرد. بنابراین تنها راه پیاده سازی Logout، ذخیره سازی توکنها در بانک اطلاعاتی و سپس حذف آنها در حین خروج از سیستم است. به این ترتیب اعتبارسنج سفارشی توکنها، از استفادهی مجدد از توکنی که هنوز هم معتبر است و منقضی نشدهاست، جلوگیری خواهد کرد:
[AllowAnonymous] [HttpGet("[action]"), HttpPost("[action]")] public async Task<bool> Logout() { var claimsIdentity = this.User.Identity as ClaimsIdentity; var userIdValue = claimsIdentity.FindFirst(ClaimTypes.UserData)?.Value; // The Jwt implementation does not support "revoke OAuth token" (logout) by design. // Delete the user's tokens from the database (revoke its bearer token) if (!string.IsNullOrWhiteSpace(userIdValue) && int.TryParse(userIdValue, out int userId)) { await _tokenStoreService.InvalidateUserTokensAsync(userId).ConfigureAwait(false); } await _tokenStoreService.DeleteExpiredTokensAsync().ConfigureAwait(false); await _uow.SaveChangesAsync().ConfigureAwait(false); return true; }
آزمایش نهایی برنامه
در فایل index.html، نمونهای از متدهای لاگین، خروج و فراخوانی اکشن متدهای محافظت شده را مشاهده میکنید. این روش برای برنامههای تک صفحهای وب یا SPA نیز میتواند مفید باشد و به همین نحو کار میکنند.
کدهای کامل این مطلب را از اینجا میتوانید دریافت کنید.