راهنمای استفاده از WebTaskScheduler در وب سایتهای ASP.NET
تمامی حقوق این ابزار و مقاله متعلق به سالار خلیل زاده است.
استفاده از این ابزار یا مقاله با ذکر منبع بلامانع است.
مقاله اصلی:
http://www.softprojects.org/KB/Artic...er.aspx?lng=fa
http://www.softprojects.org/KB/Artic...er.aspx?lng=en
معرفی:
از آنجایی که انجام وظایف در برنامه تحت وب صورتی متفاوت با برنامه های Desktop دارد همیشه این مشکل وجود داشته که برنامه های تحت وب برای برای زمانبندی انجام کارها مشکل داشته اند. با ظهور ASP.NET و تکنولوژی های موجود در آن این امکان به طور غیر مستقیم فراهم است تا این مشکل را برطرف کنیم. این ابزار نیز برای همین منظور و برای رفع این مشکل ساخته شده است. روش کار این ابزار استفاده از امکانات سیستم Caching است که در ASP.NET فراهم شده است.
روش استفاده سریع:
روش استفاده بسیار آسان است. مراحل زیر را به ترتیب انجام دهید:
1. در قدم اول باید فایل SalarSoft.WebTaskScheduler.dll را به لیست رفرنس (Reference) های خود اضافه کنید. برای این کار در Visual Studio روی نام پروژه خود کلیک راست کرده و گزینه Add Reference را انتخاب کنید و سپس فایل ذکر شده را اضافه کنید.
2. در قدم بعدی باید تابعی برای فراخوانی های خود معرفی کنید. این تابع فرمت خاصی دارد که به قرار زیر است:
C#
static void MyTask_CallBack(WebTaskEventArgs e)
{
// کدهای خود را اینجا بنویسید
}
VB.NET
Shared Sub MyTask_Callback(ByVal e As WebTaskEventArgs)
' کدهای خود را اینجا بنویسید
End Sub
اگر توجه کرده باشید تنها نکته مهم در تعریف این تابع تنهای ورودی پارامتر تابع از نوع WebTaskEventArgs است. درون این تابع شما کد های خود را خواهید نوشت و این تابع در فواصل زمانی که در مرحله بعدی تعریف می کنیم فراخوانی خواهند شد. (لطفا به تذکرات آخر مقاله توجه کنید).
3. در قدم بعدی باید لیست وظایف خود را اضافه کنید. برای اضافه کردن درخواست کافی است که تابع Add را فراخوانی کنید.
در مثال زیر ما قصد داریم تا task را برای هفته ای یک بار تعیین کنیم.
C#
WebTaskScheduler.Add("MyTask", MyTask_CallBack, TaskExecutePeriod.Weekly);
برای VB.NET کمی به مراحل اضافی تر نیاز است که در تابع زیر به طور مختصر نوشته و توضیح داده میشود:
VB.NET
Sub AddMyTask()
'Line 1
Dim onMytaskCallBack As WebTaskExecuteCallback
'Line 2
onMytaskCallBack = New WebTaskExecuteCallback(AddressOf MyTask_CallBack)
'Line 3
WebTaskScheduler.Add("MyTask", onMytaskCallBack, TaskExecutePeriod.Weekly)
End Sub
در خط 1 متغیری از متغیری از نوع WebTaskExecuteCallback تعریف شده است. در خط دوم تابع MyTask_CallBack را به این متغیر اختصاص می دهیم و در خط 3 Task جدید با ویژگی های تعیین شده اضافه می شود.
4. تنها کاری که لازم است انجام دهید موارد 1 و 2 را در فایل Global.asax و در رویداد Application start انجام دهید. و پایان! می توانید وب سایت خود را اجرا کنید. (لطفا به تذکرات آخر مقاله توجه کنید)
معرفی ویژگی ها و امکانات:
* نحوه تعریف وظیفه جدید با استفاده از متد Add
تابع Add برای تعریف وظیفه جدید استفاده می شود. این تابع به دو صورت تعریف شده و قابل استفاده است، تعریف آن را در زیر مشاهده می کنید:
Method 1:
WebTaskScheduler.Add( String , WebTaskExecuteCallback , Integer )
Method 2:
WebTaskScheduler.Add( String , WebTaskExecuteCallback , TaskExecutePeriod )
Method 3:
WebTaskScheduler.Add( String , WebTaskExecuteCallback , TimeSpan )
در هر دو روش اول و دوم پارامتر های اول و دوم عملکرد یکسانی دارند که در یکجا توضیح داده می شود:
پارامتر اول از نوع string با نام key: در این پارامتر نام وظیفه (Task) را مشخص می کنید که البته نباید تکراری باشد. از این نام برای مدیریت Task در سایر موارد می توان استفاده کرد.
پارامتر دوم از نوع WebTaskExecuteCallback با نام callback: به این پارامتر باید نام تابع فراخوانی شونده را ارسال کنید. این همان تابعی خواهد بود که در صورت رسیدن موعد مقرر برای اجرای وظیفه (یا همان Task) اجرا خواهد شد.
تابع از نوع WebTaskExecuteCallback دارای پارامتری از نوع WebTaskEventArgs است اختیاراتی را برای مدیریت وظیفه در حال اجرا به کاربر می دهد. ( لطفا جهت مطالعه جزئیات پیرامون WebTaskEventArgs به آخر مقاله مراجعه کنید).
Method 1 پارامتر سوم از نوع Integer با نام DaysPeriod: این پارامتر فواصل زمانی روزانه را برای اجرای وظیفه تعیین می کند. برای مثال می توانید با تعیین مقدار 10 مشخص کنید که این وظیفه هر 10 روز یکبار اجرا شود.
Method 2 پارامتر سوم از نوع TaskExecutePeriod با نام period: این پارامتر فواصل زمانی اجرای وظیفه را تعیین می کند. این نوع می تواند یکی از مقادیر ( None , EveryNoon , Daily , Weekly , TwoWeekly , Monthly ) باشد. برای مثال اگر مقدار Daily ارسال شود در این صورت هر روز یکبار وظیفه اجرا خواهد شد.
Method 3 پارامتر سوم از نوع TimeSpan با نام customPeriod: این پارامتر این امکان را می دهد تا فواصل زمانی دلخواه برای اجرای وظیفه تعیین کنید. فاصله تعیین شده از همان لحظه مورد محاسبه قرار خواهد گرفت. برای مثال اگر ورودی برای 5 دقیقه داده شود، وظیفه دقیقا 5 دقیقا بعد اجرا خواهد شد.
* حذف وظیفه موجود
تابع Remove برای حذف وظیفه موجود و لغو اجرا دوباره آن مورد استفاده است. نحوه تعریف این تابع در زیر مشخص شده است:
Method 1:
Remove(string key)
Method 2:
Remove(WebTaskItem)
در متد اول نام کلید برای حذف وظیفه مورد استفاده است.
در متد دوم آیتمی از نوع وظیفه به عنوان ورودی برای حذف آن مورد استفاده است.
* بدست آورد ریز جزئیات یک وظیفه
با استفاده از تابع GetItem می توان ریز جزئیات را بدست آورد. نحوه تعریف این تابع در زیر مشخص شده است:
GetItem( string )
WebTaskItem خروجی از نوع
ورودی این کلیدی است که در ایجاد وظیفه در تابع Add تعیین شده است.
خروجی این تابع از نوع WebTaskItem است که حاوی ریز جزئیات آن وظیفه است.
* جلوگیری از تداخل همزمانی در تغییر وظایف
دو متد Lock و Unlock برای قفل کردن و باز کردن قفل دسترسی به این ابزار در نظر گرفته شده است.
این گزینه پیشرفته ای است برای زمانی که ممکن است درخواست های همزمان از چند thread مختلف برای این کامپوننت شود و این باعث این اختلال در انجام عملیات آن شود. با استفاده از این توابع در یک لحظه فقط یک درخواست به این کامپوننت دسترسی خواهد داشت و سایر درخواست ها در انتظار پایان آن خواهند بود.
پیاده سازی این توابع به صورت زیر است.
Method 1:
Lock()
Method 2:
Lock( wait )
Method 3:
Unlock()
برای قفل کردن دسترسی متد lock و برای آزاد کردن دسترسی متد unlock باید فراخوانی شود.
متد دوم Lock دارای پارامتر wait از نوع bool است که تعیین میکند که اگر درخواست دیگری در حال اجرا است یا برای پایان ان صبر کند یا نه.
نکته: این دو تابع را همیشه با بلوک try...Finally پیاده سازی کنید.
نمونه مثال از پیاده سازی این توابع:
C#:
WebTaskScheduler.Lock();
try
{
WebTaskScheduler.Add("MyTask", MyTask_CallBack, 1);
}
finally
{
WebTaskScheduler.Unlock();
}
VB.NET:
WebTaskScheduler.Lock()
Try
Dim onMytaskCallBack As WebTaskExecuteCallback
onMytaskCallBack = New WebTaskExecuteCallback(AddressOf MyTask_CallBack)
WebTaskScheduler.Add("MyTask", onMytaskCallBack, TaskExecutePeriod.Weekly)
Finally
WebTaskScheduler.Unlock()
End Try
* معرفی TaskExecutePeriod به عنوان ورودی تابع Add
نام توضیح
None :
باعث اجراهای پی در پی و با فواصل چند ثانیه ای خواهد شد. (توصیه نمی شود)
EveryNoon :
اجرای وظیفه هر روز ظهر خواهد بود.
Daily :
اجرای وظیفه هر شب خواهد بود.
Weekly:
هر هفته یکبار، آخرین روز هفته بر اساس تاریخ میلادی شب وظیفه اجرا خواهد شد.
TwoWeekly:
هر دو هفته یکبار آخرین روز هفته بر اساس تاریخ میلادی وظیفه اجرا خواهد شد.
Monthly :
هر ماه یکبار آخرین روز ماه بر اساس تاریخ میلادی وظیفه اجرا خواهد شد.
ShamsiWeekly :
هر هفته یکبار، آخرین روز هفته بر اساس تاریخ شمسی شب وظیفه اجرا خواهد شد.
ShamsiTwoWeekly :
هر دو هفته یکبار آخرین روز هفته بر اساس تاریخ شمسی شب وظیفه اجرا خواهد شد.
ShamsiMonthly :
هر ماه یکبار آخرین روز ماه بر اساس تاریخ شمسی شب وظیفه اجرا خواهد شد.
* معرفی WebTaskEventArgs به عنوان پارامتر CallBack
این کلاس دارای دو مشخصه با نام های TaskItem و CanContinue می باشد.
مقدار CanContinue مشخص کننده این است که اجرای این وظیفه در فواصل زمانی بعدی تکرار شود یا نه. با قرار دادن مقدار false به آن وظیفه به طور خودکار حذف خواهد شد. مقدار این مشخصه به طور پیش فرض true است.
مشخصه TaskItem جزئیات وظیفه در حال اجرا یا همان جاری را نشان میدهد که می توانید آنها را تغییر دهید. مثلا اگر اجرای وظیفه را بر هفته ای تنظیم کرده بودید میتوانید آن را به روزانه تغییر دهید.
تعدادی نکته:
1. مهم: برای وب سایت ASP.NET خود همیشه سعی کنید که وظایف را در رویداد Application_Start از Global.asax اضافه کنید. این به این علت است که وظایف اضافه شده در دیسک ذخیره نمیشوند و با Restart شدن وب سایت از بین می روند.
2. وظایف ایجاد شده در دیسک ذخیره نمیشوند و ممکن است با Restart شدن وب سایت از بین بروند. (در نگارش های بعدی امکاناتی افزوده خواهد شد.)
3. به کلاس WebTaskScheduler در تمام وب سایت خود می توانید دسترسی داشته باشد.
پایان!
