I’ll review the basic steps on creating a SharePoint custom event handler.
You begin by opening up Microsoft Visual Studio 2005 and create a new class project. Reference the Microsoft.SharePoint assembly and then rename the default.cs class to the name that you want to give to your event handler. Also, remember to add your using statement for Microsoft.SharePoint.
Depending on which type of event handler you are wanting to write, will determine the proper SharePoint class to derive from. A breakdown of the available SharePoint classes to derive from are as follows:
- List Items – SPItemEventReceiver
- List Columns – SPListEventReceiver
- Site – SPWebEventReceiver
- Email - SPEmailEventReceiver
At this point, you need to make a decision on whether you want to use Asynchronous or Synchronous events in your event handler. In order to determine which one you want, first decide if you want the event to fire before or after the event.
Asynchronous calls occur after the event, and do not block any code being executed in SharePoint. On the flipside, synchronous calls occur before the event, will block code being executed in SharePoint until your custom event handler is completed.
For a list of the available methods for each class, refer to Microsoft’s site:
SPItemEventReceiver Methods
http://msdn.microsoft.com/en-us/library/microsoft.sharepoint.spitemeventreceiver_methods.aspx
SPListEventReceiver Methods
http://msdn.microsoft.com/en-us/library/microsoft.sharepoint.splisteventreceiver_methods.aspx
SPWebEventReceiver Methods
http://msdn.microsoft.com/en-us/library/microsoft.sharepoint.spwebeventreceiver_methods.aspx
SPEmailEventReceiver Methods
http://msdn.microsoft.com/en-us/library/microsoft.sharepoint.spemaileventreceiver_methods.aspx
Once you make your decision on what type of event receiver and also what type of method call you will be using, write out the override method . I will discuss further on manipulating particular methods.
Creating a Strong Name Key
After completing your method, you will need to sign the assembly. You can do this by going into solution explorer and right clicking your project and selecting properties. Then, click the Signing tab, then select Sign the Assembly, then select Choose a strong name key file and click “<New…>”. Type a name into the Key file name box (usually the name of your project). It needs to be in the format of xxxxxx.snk. You can set a password if you want, and click OK.
Creating Event Receiver to be installed as a Feature
Right click on your event handler project and select Add / New Folder. Name the folder as the same name as the project or similar. Add to blank XML files under the folder. Name the XML files as elements.xml and the other feature.xml.
In the feature.xml file, it should follow the following format:
<Feature Scope="Web"
Title="My Event Handler"
Description ="Description goes here."
Id="F141E5EA-796E-4807-AB86-43F5DC560371"
xmlns="http://schemas.microsoft.com/sharepoint/">
<ElementManifests>
<ElementManifest Location="elements.xml"/>
</ElementManifests>
</Feature>
For further explanation, refer to the Microsoft site for all the available nodes.
http://msdn.microsoft.com/en-us/library/ms436075.aspx
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
<Receivers ListTemplateId="101">
<Receiver>
<Name>MyEventHandler</Name>
<Type>ItemAdded</Type>
<SequenceNumber>10000</SequenceNumber>
<Assembly>MyEventHandler, Version=1.0.0.0, Culture=neutral, PublicKeyToken=1cd942f82aed8c82</Assembly>
<Class>MyEventHandler.EventHandler</Class>
<Data></Data>
<Filter></Filter>
</Receiver>
</Receivers>
</Elements>
In the elements.xml, the ListTemplateId refers to which list to associate the event handler. 101 = document library. For a description of the available id, see here: http://msdn.microsoft.com/en-us/library/ms462947.aspx
The <Type> node refers to the method that will be raised when the action takes place. For multiple methods, you will need multiple <Receiver> nodes. <SequenceNumber>node refers to the order of execution.
Add a text file to the root of the project and rename it to cab.ddf and input the following:
;** MyEventHandler.wsp **
.OPTION EXPLICIT
.Set CabinetNameTemplate= MyEventHandler.wsp
.Set DiskDirectoryTemplate=CDROM
.Set CompressionType=MSZIP
.Set UniqueFiles="ON"
.Set Cabinet=on
.Set DiskDirectory1=Package
;**************************************************
manifest.xml manifest.xml
MyEventHandler\elements.xml MyEventHandler \elements.xml
MyEventHandler \feature.xml MyEventHandler \feature.xml
bin\debug\ MyEventHandler.dll MyEventHandler.dll
Then add another text file and rename that one to installer.bat. The following should be inputted:
Add a new xml file to the root of the project and rename it to manifest.xml and input the following:
<?xml version="1.0" encoding="utf-8" ?>
<Solution xmlns="http://schemas.microsoft.com/sharepoint/" SolutionId="BF2A762B-A158-456c-BCA5-38120E87D982">
<FeatureManifests>
<FeatureManifest Location="MyEventHandler\feature.xml"/>
</FeatureManifests>
<Assemblies>
<Assembly DeploymentTarget="GlobalAssemblyCache" Location="MyEventHandler.dll">
</Assembly>
</Assemblies>
</Solution>
Save all your work and build your project.