About SharePoint Event Receiver. 学习笔记.

Summarized from http://hristopavlov.wordpress.com/2009/02/24/understanding-sharepoint-event-receivers/

 

1. All list item, list and web event receivers in SharePoint [with the exception of the ListItemFileConverted receiver(除了这个类型)] are run from the SPRequest unmanaged class.
2. There are two types of event receivers – synchronous (such as ItemAdding and ItemUpdating) and asynchronous (such as ItemAdded and ItemUpdated).
3. Because the event receivers are implemented in managed code, the unmanaged SPRequest class needs a way to invoke them. This is done via the ISPEventManager COM interface which is implemented by the Microsoft.SharePoint.SPEventManager internal class.

   [ComImport, SuppressUnmanagedCodeSecurity, InterfaceType((short)1), Guid("BDEADF0F-C265-11D0-BCED-00A0C90AB50F")]
   
    public interface ISPEventManager
   
   {
   
       [MethodImpl(MethodImplOptions.InternalCall, MethodCodeType = MethodCodeType.Runtime)]
   
       void ExecuteItemEventReceivers(
   
           ref byte[] userToken, ref objecteventReceivers, ref ItemEventReceiverParams itemEventParams, 
   
           out objectchangedFields, outEventReceiverResult eventResult, out stringerrorMessage);
   
    
   
       [MethodImpl(MethodImplOptions.InternalCall, MethodCodeType = MethodCodeType.Runtime)]
   
       void EnqueueItemEventReceivers(ref byte[] userToken, ref objecteventReceivers, ref ItemEventReceiverParams itemEventParams);
   
    
   
       [MethodImpl(MethodImplOptions.InternalCall, MethodCodeType = MethodCodeType.Runtime)]
   
       void ExecuteListEventReceivers(
   
           ref byte[] userToken, ref objecteventReceivers, ref ListEventReceiverParams ListEventParams, 
   
           outEventReceiverResult eventResult, out stringerrorMessage);
   
    
   
       [MethodImpl(MethodImplOptions.InternalCall, MethodCodeType = MethodCodeType.Runtime)]
   
       void EnqueueListEventReceivers(ref byte[] userToken, ref objecteventReceivers, ref ListEventReceiverParams ListEventParams);
   
    
   
       [MethodImpl(MethodImplOptions.InternalCall, MethodCodeType = MethodCodeType.Runtime)]
   
       void ExecuteWebEventReceivers(
   
           ref byte[] userToken, ref objecteventReceivers, ref WebEventReceiverParams webEventParams, 
   
           outEventReceiverResult eventResult, out stringerrorMessage);
   
    
   
       [MethodImpl(MethodImplOptions.InternalCall, MethodCodeType = MethodCodeType.Runtime)]
   
       void EnqueueWebEventReceivers(ref byte[] userToken, ref objecteventReceivers, ref WebEventReceiverParams webEventParams);
   
   }
    

4. Both synchronous and asynchronous event receivers will execute in the same process that has made the change that resulted in the event receivers being called.
   同步和非同步的event receiver都在触发event进程中被执行的.
5. The asynchronous event receivers may need some time to complete (could be a lot of time) and if you close your MyWinFormsApp.exe immediately after you have added the file, and while the event receivers are still running, what will happen is that they will be terminated and some of them may not run at all.
6. The asynchronous event receivers will be run in their own thread from the System.Threading.ThreadPool.
   Switching between threads is a very resource intensive operation and if you have 100 threads running in your application or in IIS, this will pretty much slow down the process to a crawl.
   I(Hristo Pavlov)’ve seen this happening with a custom built migration tool that moves documents from one document library to another. There were some heavy ItemAdded event receivers and after few hundreds files were moved for a minute or so, it took another 45 minutes for the event receivers to complete. The migration would have been faster if after adding each file the migration tool was waiting for the event receivers to complete because after adding all the files at once 90+% of the time the process was spending in switching between the few hundred threads and only up to 10% were the actual threads running the event receivers.
7. The lifespan for the SPItemEventProperties that are passed to all item event receivers.
   a. All synchronous event receivers will share the same properties,
   b. All asynchronous event receivers will share different instance of the properties.
   c. The unmanaged SPRequest class will keep the changes to the properties done by the synchronous event receivers and will pass them to the asynchronous event receivers. 
   This could only(only?) be done from an ItemAdding or ItemUpdating event receiver. You could add anything you want to the AfterProperties collection and the information you have added will be availabe as AfterProperties in the ItemAdded and ItemUpdated event receivers.
   d. SPItemEventProperties class actually implements IDisposable and disposes the allocated site or web. The SPEventManager class makes sure to call Dispose() after the batch of event receivers have executed.
8. To use them you need to create your event receiver class to inherit from the SPSynchronousReceiver class and override the ItemAddedSynchronously method:
   a.

   public class SPTestReceiver : SPSynchronousReceiver
   
   {
   
             
   
       protected override void ItemAddedSynchronously(SPItemEventProperties properties)
   
       {
   
           // Your code goes here
   
       }
   
    
   
    
   
       // Your other item receiver overrides go here    
   
    
   
   }
   

   
   b. 

   using (SPSite site = new SPSite(“http://server/sites/test”))
   
   using (SPWeb web = site.OpenWeb())
   
   {
   
       SPList list = web.Lists["Shared Documents"];
   
    
   
       SPFile file = list.RootFolder.Files.Add(fileName, fileBytes);
   
    
   
       SPSynchronousReceiver.WaitForItemAddedReceivers(list, file.Item.ID);
   
   }
   

    

   c. 可以在页面上添加一个web control等待ItemAdded事件结束.

   <%@Register TagPrefix=”SharePointInternals” 
   
               Assembly=”SharePointInternals.SynchronousItemAdded, Version=1.0.0.0, Culture=neutral, PublicKeyToken=d7dbdc19a16aed51″ 
   
               namespace=”SharePointInternals.WebControls”%>
   
    
   
    
   
   …
   
    
   
   <asp:Content ContentPlaceHolderId=”PlaceHolderMain” runat=”server”>
   
       <SharePointInternals:WaitForItemAdded ID=”waitForItemAdded1″ runat=”server”/>
   
    
   
       … 
   
       
   
   </asp:Content>
   

    这里要注意添加control的位置.  
    If we add the web control to the ListFormTemplate used by the ListFormWebPart from EditForm.aspx, then it will wait for the event receivers to complete, but at this stage the ListItem would have been already loaded in the SPContext and the EditForm.aspx will show the field values of the list item before the ItemAdded event receivers have completed. If any of them have updated the list item then pressing OK on the EditForm.aspx will actually cause an exception:
   The file … has been modified by … on …
   （解释, 这里作者想要在ItemAdded 的 receiver执行完毕, 在editform中显示item的metadata. 如果把webcontrol添加在ListFormTemplate中, ListFormWebPart会调用ListFormTemplate, EditForm.aspx会调用ListFormTemplate, 这样EditForm.aspx在显示前也会等待Receiver执行完毕. 但是在Receiver执行之前, SPContext应经加载Item完毕. 也就是说, 显示的Item和他的metadata已经过期失效. ）

9. GENE(笔记者)添加, 提升权限是线程级的, 每个Receiver都是在独立的线程内运行的, 因此编写EventReiver的代码, 要注意权限问题, 或者在Receiver内注意提升权限.