Event Handlers – Part 2: Building and Deploying Event Handlers (Including Event Handler Starter Solution Kit)



This post is the second post of a 3 post series.


 


Post 1: Everything you need to know about MOSS Event Handlers


Post 2: Developer Solution Starter Kit (Building and deploying event handlers to MOSS)


Post 3: Registering Event Handlers plus Site Settings – Manage Event Handlers


 


Overview


In the first post, I discussed the benefits of using Event Handlers in Microsoft Office SharePoint Server 2007 (MOSS). Today I intend to discuss how to develop and deploy event handlers to your farm environment.


I have used CodePlex to host the Event Handler Solution Starter Kit Project. The solution starter kit contains two projects, one project that contains the assembly and another that contains a solution deployment package builder project.  



Download the EventHandlerSolutionStarterKit.zip to get started.


(In the third post, I will discuss the various mechanisms to attach (register) your assembly to a site, list, or content type. I will also share a cool add-on I developed for MOSS that allows you to manage event handlers via a custom Site Settings Administration Application).


 


Building Event Handlers for SharePoint


 


Development Environment


I recommend building a Virtual PC that has MOSS 2007, and Visual Studio 2005. There are numerous posts out there on how to build your environment, so I won’t go into that.


 


One point I will make is to keep a copy of virtual hard disk once you have finished building it. I find MOSS 2007 Virtual PC’s degrade over time due to defragmentation, dev, etc. It is easier to make a copy of your original hard disk and continue developing.


 




Steps


Use the following steps if you want to create your solution from scratch otherwise download the starter kit and continue from Step 7.


 


1)   Open Visual Studio 2005.


 


2)   Create a new class library project.


 


3)   Reference the Microsoft.SharePoint assembly.


 


4)   Rename the default class to the name you want to give your event handler class. E.g. ItemHandler


 


5)   Add your “using” statement: “using Microsoft.SharePoint;”


 


6)   Inherit from the following SharePoint base classes depending on what type of event handler your want to create:


a.   Site                   : SPWebEventReceiver


b.   List Columns       : SPListEventReceiver


c.   List Items           : SPItemEventReceiver


d.   Email                 : SPEmailEventReciever


 


 


7)   In your class, type “override” and let IntelliSense provide you with a list of events to override.


 


8)   Implement the logic in the overridden method(s).


 


9)   Compile, fix errors, recompile until build succeeds.


 


10)       Strongly name your assembly ( sign your assembly )


a.   Right Click your Class Library Project


b.   Select Signing Tab


c.   Choose a strong name key file:


                                         i.    <browse> = select a previously created key file.


                                        ii.    <new> = create a new key file.


 


 


 


Deploying your Assembly to staging and production


 


Steps


1) Create a solution deployment file (*.wsp file)


A solution deployment file is simply a cab file with a manifest file. It contains all the files and information of your solution. The manifest file tells SharePoint what to do with the files in your solution.


 


To get started, download my solution starter kit. This contains a visual studio deployment file creator project based on Vincent Rothwell’s fantastic visual studio deployment project template to create the *.wsp file. Have a look at his blog and codeplex project for more information on using this functionality:


 


·         Blog: VS.Net SharePoint Solution Template on CodePlex


·         CodePlex: http://www.codeplex.com/sptemplateland/


 


NOTE: I have customized the CreateManifest.vbs script in the deployment project so that it only creates the relevant entries to deploy the assembly dll to the GAC.


 


If you want to build your own deployment project from scratch or learn more about this feature of MOSS, have a look at the following articles on the Microsoft Developer Network (MSDN):


·         Solutions Overview


·         Creating a Solution


·         Deploying a Solution


·         Upgrading a Solution


·         Retracting a Solution


·         Localizing a Solution


·         Solution Schema


2) Register your wsp file using stsadm.exe with SharePoint


Once you have created your SharePoint solution deployment file, you need to tell SharePoint about this. Here are the steps you need to follow to register your solution in SharePoint:


 


·         Open up Command Prompt (Start > Run > cmd.exe)


·         Navigate to the location of stsadm.exe utility in the “12” hive by typing the following into the command prompt (assuming default installation to C: drive)


o    cd\


o    cd C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\BIN


·         Run the following command


 


stsadm.exe –o addsolution –filename C:\replacewithpathtofile\filename.wsp


  


3) Push solution to SharePoint farm


You have two options:


 


·         Navigate to Central Administration >Operations > Solution Management. You should see your newly added solution in the list.


o   Click on it to view the solution details page.


o   Select Deploy Solution on the toolbar.


 


·         Alternatively, you could replace the option above and deploy the solution via the command prompt using the following command:


 


stsadm.exe –o deploysolution –name filename.wsp –local –allowgacdeployment –allcontenturls


 


Summary


 


A sign of a great developer is the ability to put the finishing touches on the development effort. When it comes to deployment, you aim to achieve the following goals:


 


1.   Simple to deploy!


o   Use SharePoint solution deployment (*.wsp) files


o   Script the installation to deploy your wsp files


o   Document (Readme) files for any settings/ procedures to install/ “gotchas”.


 


2.   Simple to maintain!


What maintenance tasks must be performed by SharePoint Administrators? Is it documented? If you or they left the company, would your solution degrade and die a horrible death (which would inevitably be blamed on you)? Where are you storing your maintenance documentation? Have you thought of adding tasks to SharePoint Central Administration Task List to remind people of administrative tasks?


 


3.   Simple to upgrade!


This is something that we often forget to think about upfront, resulting in loss of our solution’s future agility. All solutions are developed in phases. The first phase is normally the core of the solution. Subsequent phases add on functionality to your solution. These need to be deployed to replace/ add on to your solution. SharePoint Solution Deployment manages this for you, so know and use this feature of MOSS 2007.


 


4.   Consistency and Repeatability!


This applies to how your solution is deployed to staging and production environments. You will not always be the person deploying it! Follow a standard pattern of deployment to minimise mistakes or random variations in the deployment process.  


 


If you have any questions, add a comment and time permitting, I will try to respond.


 


Goodluck!

EventHandlerSolutionStarterKit.zip

Comments (19)

  1. Anonymous says:

    This post is the third post of a 3 post series. Post 1: Everything you need to know about MOSS Event

  2. Anonymous says:

    (Si vous êtes novice sur les event handler, regarder à la fin du post ) En parcourant les forums SharePoint,

  3. Anonymous says:

    Maybe you were tasked to provide certain functionality for your SharePoint 2007 instance? Maybe windows

  4. Anonymous says:

    Maybe you were tasked to provide certain functionality for your SharePoint 2007 instance? Maybe windows

  5. Anonymous says:

    Below is a list of events that you can hook into: · Microsoft.SharePoint.SPWebEventReceiver : "Site Level"

  6. Anonymous says:

    Thanks for the article! It is compact and clear. You are the best Sharepoint author I have ever read.

  7. Anonymous says:

    This post is the second post of a 3 post series. Post 1: Everything you need to know about MOSS Event

  8. Anonymous says:

    hi,

    I want to start a workflow when an item in a list gets updated.

    I have performed the following steps:

    1. Created a workflow project in VS 2005 and deploy it at site level using feature.
    2. Created a class library project that calls the workflow in ItemUpdated event and deploy it at web level using feature.

    Problem:

    When an item is updated in the list in the site for which the features have been enabled, the ItemUpdated event doesn’t fire. It does not give any error also(i checked by writing to an event log in case of error).

    Code to attach the worklow to the list

    namespace CallItemUpdatedWf

    {

       public class AbuseHandle:SPItemEventReceiver

       {

           public override void ItemUpdated(SPItemEventProperties properties)

           {

               base.ItemUpdated(properties);

               try

               {

                   StartListWorkflow(properties);

               }

               catch (Exception ex)

               {

                   string sSource;

                   string sLog;

                   string sEvent;

                   sSource = properties.ErrorMessage;

                   sLog = "Application";

                   sEvent = "Sample Event";

                   if (!EventLog.SourceExists(sSource))

                       EventLog.CreateEventSource(sSource, sLog);

                   EventLog.WriteEntry(sSource, sEvent);

               }

           }/// <summary>

           /// Starts a workflow associated to a list programmatically.

           /// </summary>

           /// <param name="properties"></param>

           private void StartListWorkflow(SPItemEventProperties properties)

           {

               //get list item from event handler properties

               SPListItem listItem = properties.ListItem;

               using (SPWeb web = listItem.Web)

               {

                   using (SPSite site = web.Site)

                   {

                       //obtain an instance of SPWorkflowManager

                       //which will be later used to start the workflow

                       SPWorkflowManager manager = site.WorkflowManager;

                       //get item’s parent list

                       SPList parentList = listItem.ParentList;

                       //get all workflows that are associated with the list

                       SPWorkflowAssociationCollection associationCollection =

                           parentList.WorkflowAssociations;

                       //lookup and start the worflow

                       LookupAndStartWorkflow(listItem, manager,

                           associationCollection, "5276637C-3D2B-4f12-BFE6-8040040EC09B");

                   }

               }

           }

           /// <summary>

           /// Lookup and start the workflow.

           /// </summary>

           /// <param name="listItem"></param>

           /// <param name="manager"></param>

           /// <param name="associationCollection"></param>

           /// <param name="workflowId"></param>

           private static void LookupAndStartWorkflow(SPListItem listItem,

               SPWorkflowManager manager,

               SPWorkflowAssociationCollection associationCollection,

               string workflowId)

           {

               //iterate workflow associations and lookup the workflow to be started

               foreach (SPWorkflowAssociation association in associationCollection)

               {

                   //if the workflow association matches the workflow we are looking for,

                   //get its association data and start the workflow

                   Guid workflowGuid = new Guid(workflowId);

                   if (association.BaseId == workflowGuid)

                   {

                       //get workflow association data

                       string data = association.AssociationData;

                       //start workflow

                       SPWorkflow wf = manager.StartWorkflow(listItem, association, data);

                   }

               }

           }

       }

    }

    Please help.

  9. Anonymous says:

    Hi Brian!!

    thanks for this app… this realy economize lot of time…

    I have an trouble in  activate this feature on site settings…

    I receive the error "403 page require login" and the feature not activate, you have any ideia about this?

    Thanks in Advance

    Erick Souza

  10. Anonymous says:

    hallo brian

    my mail id is shital123_sai@yahoo.com

    I need your help

    I create web part having button to do a+b

    but button click event is not working

    i create it in visual studio 2005 and put dll in assembly and change config file.  

    It shows and accept everything but button click event not showing output.

  11. Anonymous says:

    HI I’m new at sharepoint,

    I have a task list and one of its columnts is "task type" of type choice (values CR or TSK).

    I would like to show some columns when task type "CR" is selected and turn on  versioning on the task list for CR task type.

    task types TSK turn version off and hide some columns.

    any assistance will be appreciated.

    Logic of what i’m saying is :

    (

    IF task_type = "CR"

    column.visible = true;

    tasklist.versioning = true;

    ELSE

    column.visible = false;

    tasklist.versioning = false )

    this needs to be applied on NEW TASK, EDIT TASK

  12. Anonymous says:

    Im trying to set the event handlers in a server with wss3 and everything deploys perfect, but the events doesn´t appear to be executing, Is there a way to receive errors or something?, Thanks.

  13. Anonymous says:

    Doesn’t look like you get around to replying to your blog often… but here goes:

    Microsofts "Room and Equipment Reservation" app template uses an EventHandler thats triggered by "Deleting". The code they wrote has the unfortunate side effect of rendering alerts almost unusable. I need to create an alert system that sends an email of the list item content when an item is deleted.

    I just need confirmation of my concept: Can I deploy an EventHandler to an existing list? Can I deploy an EventHandler where there is already one in place (and make it fire just before or just after the previous one…)?

    Looking forward to your answer.

  14. Anonymous says:

    I want to add the client side script in the item updating event handler of the page library in moss.How to do it.Your help is needed.

  15. Anonymous says:

    Hi,

    Does anyone know where the starter kit can be found, as the link in this post no longer works.

    Thanks