نحوه ساخت و پیاده سازی یک Event Handler برای شرپوینت

سلام به همه دوستان

در انجمنهای سایت سوالهای زیادی در مورد نحوه ساخت و ایجاد Event Handler برای لیستهای شرپوینتی مطرح شده بود که تصمیم گرفتم در این مقاله به صورت کامل چگونگی ساخت Event Handler در شیرپوینت را با مثالی برای شما تشریح کنم..پس با من همراه باشید.

Event Handler چیست ؟

Event Handler به شما اجازه می دهد تا عملیات خاص و تعریف شده ای را بر روی رویدادهایی که در لیستها(Lists) ، کتابخانه اسناد(Document Library) و Content Type های سایت شرپوینتی اتفاق می افتند، انجام دهید. این رویدادها می توانند متفاوت باشند، مانند اضافه کردن یک آیتم ، حذف یک آیتم، آپدیت یک آیتم و …. .

انواع رویدادها عبارتند از :

ItemAdded
ItemAdding
ItemAttachmentAdded
ItemAttachmentAdding
ItemAttachmentDeleted
ItemAttachmentDeleting
ItemCheckedIn
ItemCheckedOut
ItemCheckingIn
ItemCheckingOut
ItemDeleted
ItemDeleting
ItemFileConverted
ItemFileMoved
ItemFileMoving
ItemUncheckedOut
ItemUncheckingOut
ItemUpdated
ItemUpdating

رویدادهای Synchronous و Asynchronous :

رویداد Synchronous : رویدادهایی هستند که با ing مشخص شده اند مانند ItemAdding که بدان معنی است که Event Handler قبل از افزودن یک آیتم در دیتابیس، عمل خاصی را انجام دهد.این امکان به ما کمک خواهد کرد تا قبل از ثبت آیتمی در لیست تغییراتی را در آن اعمال کنیم و سپس آیتم ذخیره شود.

رویداد Asynchronous :رویدادهایی هستند که با ed مشخص شده اند مانند ItemAdded که بدان معنی است که Event Handler پس از تکمیل فرایند اضافه شدن یک آیتم در دیتابیس، عمل خاصی را انجام دهد.

کلاسهای پایه :

برای نوشتن Event Handler کلاسهای پایه ای وجود دارند که بر حسب نیاز می توانید هنگام برنامه نویسی Event Handler از آنها استفاده کنید. این کلاسهای عبارتند از :

SPWebEventReciever : شما می توانید با استفاده از این کلاس یک Event Handler بنویسید و هنگامیکه یک سایت از یک مجموعه سایت حذف شد و یا به آن اضافه شد، اجرا شود.

SPFeatureEventReciever : شما می توانید یک Event Handler بنویسید تا با فعال یا غیرفعال کردن و همچنین نصب و حذف یک Feature از سایت اجرا شود.

SPListEventReciver : از این کلاس زمانی در Event Handler استفاده می شود که تغییراتی بر روی یک لیست اعمال شده باشد یا یک Content Type به آن اضافه یا حذف شده باشد.

SPItemEventReciever : از این کلاس زمانی در Event Handler استفاده می شود که تغییراتی از قبیل اضافه، حذف، آپدیت بر روی یک آیتم از یک لیست صورت گرفته باشد.

پیاده سازی یک Event Handler :

پس از آشنایی با مفاهیم Event Handler ، اکنون به نحوه پیاده سازی آن می پردازیم :

۱- یک لیست شرپوینتی با نام Customers ایجاد کنید.

۲- فیلد Title را به Name تغییر نام دهید. و دو فیلد دیگر با نامهای Tel و Email ایجاد کنید.

( فیلدهای فوق مشخصات مشتری های را در لیست Customers نگهداری می کنند. تصمیم داریم یک Event Handler برای لیست Customers ایجاد کنیم تا در صورتیکه نام مشتری به صورت تکراری توسط کاربر ثبت شد، به کاربر پیغامی جهت تکراری بودن نام مشتری داده شود و اگر نام مشتری موجود نبود، اجازه ثبت اطلاعات به کاربر داده شود )

۳- حال برنامه ویژوال استودیو ۲۰۰۵ یا ۲۰۰۸ را باز کرده و یک پروژه جدید از نوع Class Library و با نام CustomersListEventHandler ایجاد کنید.

۴- پس از ایجاد شدن پروژه در قسمت Reference پروژه کلیک راست کرده و Add Reference را انتخاب کنید و از لیست موجود Windows SharePoint Services را انتخاب و اضافه کنید.

۵- در قسمت بالای کلاس و در بخش Using، مقدار زیر را وارد کنید :

Using Microsoft.SharePoint;

۶- نام کلاس Class1.cs را به CustomerItemER.cs تغییر دهید و آنرا از کلاس SPItemEventReciver به ارث ببرید.

public class CustomerItemER : SPItemEventReceiver
    {

    }

۷- چون تصمیم داریم تا قبل از ذخیره و ثبت اطلاعات توسط کاربر، مقدار نام مشتری یا Name را چک کنیم، پس نیاز به رویداد ItemAdding برای این منظور داریم. حال متد زیر را می نویسیم :

public override void ItemAdding(SPItemEventProperties properties)
        {
            base.ItemAdding(properties);
        }

آرگومان properties در کد فوق شامل اطلاعاتی در مورد خصوصیات زیر می باشد :

,ErrorMessage , Status , ListId , ListTitle , ListItem , ListItemId , BeforeProperties , AfterProperties CurrentUserId , SiteId , WebUrl

۸- در کد برنامه نیاز داریم تا ابتدا چک کنیم که آیتم Name یا نام مشتری در لیست موجود هست یا نه! برای اینکار از آبجکت SPQuery به همراه CAML جهت پرس و جوی اطلاعات موجود در لیست استفاده می کنیم. در انتها اگر نام مشتری موجود نبود، اطلاعات ذخیره خواهد شد، در غیر اینصورت پیامی به کاربر جهت تکراری بودن نام مشتری نمایش داده خواهد شد.

کد مربوطه به صورت زیر خواهد بود :

public override void ItemAdding(SPItemEventProperties properties)
       {
           string CustomerName = properties.AfterProperties["Title"].ToString();
           
           using (SPWeb web = properties.OpenWeb())
           {
               SPList list = web.Lists[properties.ListId];
               SPQuery spquery = new SPQuery();
               spquery.Query = string.Format
               ("<Where><Eq><FieldRef Name=\"Title\" /><Value Type=\"Text\">{0}</Value></Eq></Where>", 
               CustomerName);
               SPListItemCollection items = list.GetItems(spquery);
               if (items != null && items.Count > 0)
               {
                   properties.ErrorMessage = string.Format
                       ("مشتری با نام {۰} موجود می باشد.", CustomerName);
                   properties.Status = SPEventReceiverStatus.CancelWithError;
                   properties.Cancel = true;
               }
           }
       }

۹- اکنون کد مربوط به Event Handler کامل شد و نیاز داریم تا توسط Feature ای آنرا بر روی سایت و لیست Customers فعال کنیم.

۱۰- چون نیاز داریم تا این Event Handler را در GAC اضافه کنیم باید برای آن یک Sign key تعریف کنیم. برای اینکار بر روی پروژه CustomersListEventHandler کلیک راست و Properties و سپس تب Signing را انتخاب کنید. گزینه sign the assembly را انتخاب و سپس New را کلیک کنید و در قسمت نام key را وارد کنید و سپس ok نمایید و تغییرات را ذخیره کنید. (شکل زیر)

۱۱- حال پروژه را Build کنید.

۱۲- ساختار فولدری زیر را در پروژه ایجاد کنید و در انتها داخل پوشه CustomersListEventHandler دو فایل xml با نام های feature.xml و elements.xml ایجاد کنید.

محتوای فایل feature.xml شامل اطلاعاتی در مورد feature ای است که جهت فعال کردن Event Handler ساخته میشود. کد زیر را داخل آن کپی کنید :

<?xml version="1.0" encoding="utf-8" ?>
<Feature Id="{C6053296-DA17-4bf0-AFFE-30D602A867A5}"    
         Title="Event Handlers"    
         Description="This Feature activate CustomersList Event Handler."    
         Scope="Web"    
         Hidden="FALSE"    
         xmlns="http://schemas.microsoft.com/sharepoint/">
  
  <ElementManifests>
    <ElementManifest Location="elements.xml" />
  </ElementManifests>
</Feature>

محتوای فایل elements.xml شامل اطلاعاتی در مورد Event Handler می باشد. کد زیر را داخل آن کپی کنید :

<Elements Id="{F10B79F0-A110-4614-9CD9-2B61F5D3BDCB}" xmlns="http://schemas.microsoft.com/sharepoint/">
  <Receivers ListTemplateId="100">
    <Receiver>
      <Name>ItemAdding</Name>
      <Type>ItemAdding</Type>
      <SequenceNumber>1</SequenceNumber>
      <Assembly>CustomersListEventHandler, Version=1.0.0.0, Culture=neutral, 
PublicKeyToken=77f6549835f6ace9</Assembly>
      <Class>CustomersListEventHandler.CustomerItemER</Class>
    </Receiver>
  </Receivers>
</Elements>

برای کسب اطلاعات بیشتر در مورد Receivers Element ها به این آدرس مراجعه کنید.

تغییرات را در هر دو فایل ذخیره کنید.

۱۳- حال نیاز به یک فایل راه انداز برای نصب و فعال کردن Feature نوشته شده برای Event Handler داریم. برای اینکار یک فایل با نام Install.bat در پوشه مربوط به پروژه ایجاد کنید و مقادیر زیر را داخل آن کپی کنید :

@SET TEMPLATEDIR=”c:\Program files\common files\microsoft shared\web server extensions\12\Template”

@SET STSADM=”c:\Program files\common files\microsoft shared\web server extensions\12\bin\stsadm”

@SET GACUTIL=”c:\Program Files\Microsoft SDKs\Windows\v6.0A\bin\gacutil.exe”

Echo Installing the assembly in the GAC

%GACUTIL% -if bin\debug\CustomersListEventHandler.dll

Echo Copying files to TEMPLATE directory

xcopy /e /y 12\TEMPLATE\* %TEMPLATEDIR%

Echo Installing Feature

%STSADM% -o installfeature -filename “CustomersListEventHandler\feature.xml” -force

Echo Activating Feature

%STSADM% -o activatefeature -filename “CustomersListEventHandler\feature.xml” -url “http://servername” -force

IISRESET

ساختار پروژه باید به صورت شکل زیر باشد :

۱۵- حال پس از پیاده سازی پروژه و اجرای آن، می توانیم وارد لیست Customers شده و نام مشتریان را ثبت کنیم. به صورت نمونه زیر :

حال زمانیکه نام مشتری را به صورت تکراری وارد کنیم، در هنگام ثبت اطلاعات رویداد ItemAdding فراخوانی شده و خطایی مانند خطای زیر به کاربر نمایش داده می شود :

مثالی که در بالا تشریح شد، برای آشنایی و درک اولیه مفهوم Event Handler بود. شما می توانید رویدادهای مختلف و پیچیده تری را برای سایت و لیستهای شرپوینت تعریف و ایجاد کنید. همچنین جهت پیاده سازی راحت تر و کاهش مراحل ۱۲ و ۱۳ میتوانید extension شرپوینت برای VS 2005 -2008 را نصب و از روشهای آماده تر برای پیاده سازی Event Handler ها استفاده کنید.

امیدوارم از این مقاله استفاده لازم را برده باشید.

موفق باشید.

نحوه ساخت و پیاده سازی یک Event Handler برای شرپوینت

پاسخ دهید لغو پاسخ

جستجوی مطالب

آخرین نظرات

لیست وبلاگ ها

بایگانی شمسی

پاسخ دهید لغو پاسخ

جستجوی مطالب

آخرین نظرات

لیست وبلاگ ها

تگ ها

بایگانی شمسی