Search This Blog

2009-05-10

Adding an Event Handler to a Feature

Now it’s time to take the example of the ManabFeature(Creating Feature In Sharepoint ) feature a little further by adding event handlers and programming against the WSS object model.
First, start by adding a project reference to Microsoft.SharePoint.dll. Next, locate the source file named Class1.cs and rename it to FeatureReceiver.cs. Next, add the following code.
using System;
using System.Collections.Generic;
using System.Text;
using Microsoft.SharePoint;
namespace ManabFeature
{
public class FeatureReceiver : SPFeatureReceiver
{
public override void FeatureActivated(SPFeatureReceiverProperties properties)
{
SPWeb site = (SPWeb)properties.Feature.Parent;
// track original site Title using SPWeb property bag
site.Properties["OriginalTitle"] = site.Title;
site.Properties.Update();
// update site title
site.Title = "Hello World";
site.Update();
}
public override void FeatureDeactivating(SPFeatureReceiverProperties properties)
{
// reset site Title back to its original value
SPWeb site = (SPWeb)properties.Feature.Parent;
site.Title = site.Properties["OriginalTitle"];
site.Update();
}
public override void FeatureInstalled(SPFeatureReceiverProperties properties)
{
throw new Exception("The method or operation is not implemented.");
}
public override void FeatureUninstalling(SPFeatureReceiverProperties properties)
{
throw new Exception("The method or operation is not implemented.");
}
}
}


The first thing you should notice is how you create an event handler that fires when a feature is activated or deactivated. You do this by creating a class that inherits from the SPFeatureReceiver class. As you can see, you handle events by overriding virtual methods in the base class such as FeatureActivated and FeatureDeactivating.

The FeatureActivated method has been written to update the title of the current site using the WSS object model. Note the technique used to obtain a reference to the current site–the properties parameter is used to acquire a reference to an SPWeb object. The properties parameter is based on the SPFeatureReceiverProperties class that exposes a Feature property that, in turn, exposes a Parent property that holds a reference to the current site. The site title is changed by assigning a new value to the Title property of the SPWeb object and then calling the Update method.
Also note that this feature has been designed to store the original value of the site Title so that it can be restored whenever the feature is deactivated. This is accomplished by using a persistent property bag scoped to the site that is accessible through an SPWeb object’s Properties collection. Note that many of the objects in the WSS object model have a similar Properties property, which can be used to track name-value pairs using a persistent property bag. WSS handles persisting these named value pairs to the content database and retrieving them on demand.

Now that we have written the code for the feature’s two event handlers, it’s time to think about what’s required to deploy the HelloWorld.dll assembly. The first thing to consider is that this assembly DLL must be deployed in the Global Assembly Cache (GAC), which means you must add a key file to the project in order to sign the resulting output DLL during compilation with a strong name.

Create the strong name "ManabFeature.snk" by click on Project->ManabFeature Properties->Signing->Check the checkbox Sign the assembly->click on "new" under the dropdown "Choose a strong name key file"->write ManabFeature as the Key file name and uncheck the password option



The next step is to update the feature.xml file with two new attributes so that WSS knows that there are event handlers that should be fired whenever the feature is activated or deactivated. This can be accomplished by adding the ReceiverAssembly attribute and the ReceiverClass attribute, as shown here.

<Feature Id="8684D4A9-1D76-4504-8142-65F5384B1756" Title="Manab Feature" Description="This is my very first custom feature" Scope="Web" Hidden="FALSE" ImageUrl="menuprofile.gif" ReceiverAssembly="ManabFeature, Version=1.0.0.0, Culture=neutral, PublicKeyToken=9d6bb69ab1a4acd7" ReceiverClass="ManabFeature.FeatureReceiver" xmlns="http://schemas.microsoft.com/sharepoint/"&gt;
<ElementManifests> <ElementManifest Location="elements.xml" /> </ElementManifests>
</Feature>


The ReceiverAssembly attribute should contain the four-part name of an assembly that has already been installed in the GAC. The ReceiverClass attribute should contain the namespace-qualified name of a public class within the receiver assembly that inherits SPFeatureReceiver.
Once you have made these changes to the feature.xml file, you should be able to test your work. When you rebuild the HelloWorld project, Visual Studio should run the install.bat file to copy the updated version of the feature.xml file to the WSS FEATURES directory and to install the updated version of feature.xml with WSS. The build process should also compile HelloWorld.dll with a strong name and install it in the GAC. Note that you will likely be required to run an IISRESET command to restart the IIS worker process. This is due to the fact that features and assemblies loaded from the GAC are cached by WSS within the IIS worker process.
At this point, you should be able to test your work by activating and deactivating the feature within the context of a WSS site. When you activate the site, it should change the Title of the site to “Hello World.” When you deactivate the feature, it should restore the Title of the site to the original value.

No comments: