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.
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
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.
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
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:
· 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):
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
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.