Develop and deploy a SharePoint Event Receiver from the scratch<\/p>\n
There are many information peaces on the internet how to build a decent working event receiver in SharePoint \u2013 mainly good, but still, only peaces. I\u2019ll try to present here a complete and quick \u201chow to\u201d guide – from making decision which event we want to catch until the event deployment.<\/p>\n
<\/p>\n
What you will not find here is a description of developing event handlers using Windows SharePoint Services 3.0 Tools: Visual Studio 2008 Extensions<\/a> \u2013 you cannot use them in x64 environments, and \u201cNull reference exception\u201d by deployment pops up much too often for my taste. Well, we are all waiting for 1.3 version, but until then\u2026<\/p>\n SharePoint is quite rich with the events it exposes. We can categorize SharePoint events in two different categories: by the \u201clevel\u201d which fires the event (site, list, item), and by the type of the event (synchronous and asynchronous).<\/p>\n What means synchronous \/ asynchronous?<\/p>\n As an example of synchronous and asynchronous events we can take item-level events \u201cItemAdding<\/em>\u201d and \u201cItemAdded<\/em>\u201d \u2013 by handling of \u201cItemAdding<\/em>\u201d we can take a look what that item is, and, if necessary, cancel the adding and display the error message in the SharePoint page to the user. When handling \u201cItemAdded<\/em>\u201d, we know that the item is already in the SharePoint list, but we can start some post-add actions with that item.<\/p>\n Complete table of SharePoint events you can find in my previous post<\/a>.<\/p>\n In this example, we are going to create a simple receiver, which will handle two Asynchronous events (ItemAdded<\/em> and ItemUpdated<\/em>) in all Document and Picture libraries at one SharePoint web site, and deploy it as a web site – level feature.<\/p>\n In the code which handles these two events, we are then going to break permissions inheritance for given item and to set the custom item-level based permissions.<\/p>\n We want to deploy our event receiver as a feature, so, first of all, we have to create a Feature Folder in the Features setup directory (Local_Drive:Program FilesCommon FilesMicrosoft Sharedweb server extensions12TEMPLATEFEATURES<\/span>). Let\u2019s say, our feature will be named \u201cSet Items Permissions Event Handler<\/em>\u201d, so we name our Feature Folder as \u201cPermissionsEventHandler<\/em>\u201d.<\/p>\n A Feature folder (PermissionsEventHandler<\/em>) may contain only a Feature.xml file (which describes our feature), or it may contain a Feature.xml file and any number of supporting element files. In our case, Feature folder will, beside the Feature.xml, contain only Elements.xml file, which will describe which events we want to receive and handle.<\/p>\n So, we have made the \u201cPermissionsEventHandler\u201d folder, and our Feature.xml and Elements.xml files in it. Let\u2019s look at the structure of the both XML files:<\/p>\n <\/p>\n <\/p>\n <\/p>\n <\/p>\n <\/p>\n <\/p>\n <\/p>\n <\/p>\n <\/p>\n <\/p>\n <\/p>\n <\/p>\n <\/p>\n <\/p>\n<\/div>\n<\/div>\n <\/p>\n In the first line, we define the feature scope, it\u2019s a kind of the feature visibility: from which hierarchy level will our feature be accessible. We want to have this feature only at one SharePoint Web site, so our scope is going to be Web, but it can vary between Farm<\/em> (SharePoint Farm), WebApplication <\/em>(SharePoint application), Site<\/em> (site collection), and Web (SharePoint web site). Here you can find out more about scopes<\/a>.<\/p>\n In the lines 2-5, we see the feature name, description and Guid. We create the feature guid ourselves, and it will serve as the unique identifier for this feature which we will use later.<\/p>\n In the lines 6-8 we create a reference to the Elements.xml manifest file, which will define events we want to handle.<\/p>\n In the lines 9-13 we can define Feature Properties<\/em>, you can consider it as kind of the string resources for our feature \u2013 they are actually key\/value pairs. In this case we have stored the names of the SharePoint groups to which we are going to give permissions to this item after we break inheritance, so that we don\u2019t have to hard code these names in our source code.<\/p>\n Our event receiver has to catch the following events: ItemAdded and ItemUpdated at all the Document Libraries and Picture libraries on the SharePoint site on which the feature has been activated.<\/p>\n This is exactly what we have to describe in the Elements.xml file of our feature: which events we hook onto, and which types of the lists\/libraries we want to observe.<\/p>\n We know the events (ItemAdded, ItemUpdated), we still need to know the codes for the lists and libraries we want to \u201cobserve\u201d. In our case 101<\/strong> is a standard document library, and 109<\/strong> is a standard picture library. Full list of the list and library types you can find here<\/a>.<\/p>\n So, let\u2019s look at the Elements.xml with necessary definitions:<\/p>\n <\/p>\n <\/p>\n <\/p>\n <\/p>\n <\/p>\n <\/p>\n <\/p>\n <\/p>\n <\/p>\n <\/p>\n <\/p>\n <\/p>\n <\/p>\n <\/p>\n <\/p>\n <\/p>\n <\/p>\n <\/p>\nEvents<\/h4>\n
\n
Defining a feature for our event receiver<\/h4>\n
\n
Feature.xml<\/h5>\n
1:<\/span> <<\/span>Feature<\/span> Scope<\/span>=\"Web\"<\/span><\/pre>\n 2:<\/span> Title<\/span>=\"Set Items Permissions Event Handler\"<\/span><\/pre>\n 3:<\/span> Description<\/span> = \"Sets the item permissions immediately upon item is added or edited\"<\/span><\/pre>\n 4:<\/span> Id<\/span>=\"98D6B8CB-1C6A-469c-9119-717AEBE68515\"<\/span><\/pre>\n 5:<\/span> xmlns<\/span>=\"http:\/\/schemas.microsoft.com\/sharepoint\/\"<\/span>><\/span><\/pre>\n 6:<\/span> <<\/span>ElementManifests<\/span>><\/span><\/pre>\n 7:<\/span> <<\/span>ElementManifest<\/span> Location<\/span>=\"Elements.xml\"<\/span>\/><\/span><\/pre>\n 8:<\/span> <\/<\/span>ElementManifests<\/span>><\/span><\/pre>\n 9:<\/span> <<\/span>Properties<\/span>><\/span><\/pre>\n 10:<\/span> <<\/span>Property<\/span> Key<\/span>=\"OwnersGroupName\"<\/span> Value<\/span>=\"MySiteOwners\"<\/span>\/><\/span><\/pre>\n 11:<\/span> <<\/span>Property<\/span> Key<\/span>=\"VisitorsGroupName\"<\/span> Value<\/span>=\"MySiteVisitors\"<\/span>\/><\/span><\/pre>\n 12:<\/span> <<\/span>Property<\/span> Key<\/span>=\"ContributorsGroupName\"<\/span> Value<\/span>=\"MySiteContributors\"<\/span>\/><\/span><\/pre>\n 13:<\/span> <\/<\/span>Properties<\/span>><\/span><\/pre>\n 14:<\/span> <\/<\/span>Feature<\/span>><\/span><\/pre>\nElements.xml<\/h5>\n
1:<\/span> <<\/span>Elements<\/span> xmlns<\/span>=\"http:\/\/schemas.microsoft.com\/sharepoint\/\"<\/span>><\/span><\/pre>\n 2:<\/span> <<\/span>Receivers<\/span> ListTemplateId<\/span>=\"101\"<\/span>><\/span><\/pre>\n 3:<\/span> <<\/span>Receiver<\/span>><\/span><\/pre>\n 4:<\/span> <<\/span>Name<\/span>><\/span>DocLibraryPermissionsEventHandlerOnAdded<\/<\/span>Name<\/span>><\/span><\/pre>\n 5:<\/span> <<\/span>Type<\/span>><\/span>ItemAdded<\/<\/span>Type<\/span>><\/span><\/pre>\n 6:<\/span> <<\/span>SequenceNumber<\/span>><\/span>10000<\/<\/span>SequenceNumber<\/span>><\/span><\/pre>\n 7:<\/span> <<\/span>Assembly<\/span>><\/span>PermissionsEventHandler, Version=1.0.0.0, Culture=neutral, PublicKeyToken=67d615643aea660a<\/<\/span>Assembly<\/span>><\/span><\/pre>\n 8:<\/span> <<\/span>Class<\/span>><\/span>PermissionsEventHandler.PermissionsHandler<\/<\/span>Class<\/span>><\/span><\/pre>\n 9:<\/span> <<\/span>Data<\/span>><\/<\/span>Data<\/span>><\/span><\/pre>\n 10:<\/span> <<\/span>Filter<\/span>><\/<\/span>Filter<\/span>><\/span><\/pre>\n 11:<\/span> <\/<\/span>Receiver<\/span>><\/span><\/pre>\n 12:<\/span> <<\/span>Receiver<\/span>><\/span><\/pre>\n 13:<\/span> <<\/span>Name<\/span>><\/span>DocLibraryPermissionsEventHandlerOnUpdated<\/<\/span>Name<\/span>><\/span><\/pre>\n 14:<\/span> <<\/span>Type<\/span>><\/span>ItemUpdated<\/<\/span>Type<\/span>><\/span><\/pre>\n 15:<\/span> <<\/span>SequenceNumber<\/span>><\/span>10001<\/<\/span>SequenceNumber<\/span>><\/span><\/pre>\n 16:<\/span> <<\/span>Assembly<\/span>><\/span>PermissionsEventHandler, Version=1.0.0.0, Culture=neutral, PublicKeyToken=67d615643aea660a<\/<\/span>Assembly<\/span>><\/span><\/pre>\n 17:<\/span> <<\/span>Class<\/span>><\/span>PermissionsEventHandler.PermissionsHandler<\/<\/span>Class<\/span>><\/span><\/pre>\n 18:<\/span> <<\/span>Data<\/span>><\/<\/span>Data<\/span>><\/span><\/pre>\n