Monday, December 1, 2008

Extending SharePoint Server 2007 by using Features

Introduction

The Feature Framework has been extended to allow developers to create custom Features. Features can be deployed by using SharePoint Portal Server 2007 new form of deployment, namely Solution Deployment. Solutions are custom packages (e.g. WSP file) or redistributable CAB files, created by developers and deployed by SharePoint Administrators. Administrator can deploy Features to the individual site or to all Web front End Servers.
In this article, I will walk-through Creating and deploying an Event Handler Feature, which can be activated on the Web or Site, Site Collection, Web Application or Farm Level.

Components of Feature

A Feature can include any number of files, but it must include a Feature.xml file. The Feature.xml file, or Feature manifest, is the driver of the Feature, and this is the first file SharePoint looks at when invoking a Feature.
Features are organized in folders under the Features directory located under 12 hives; Where SharePoint Server 2007 puts all of its system files, at the following path: %SystemDrive%\Program Files\Common Files\Microsoft Shared\web server extensions\12.
In addition to the Feature.xml file, Features can include sub-folders and supporting files, such as element files that include for example, event handler references, ASPX pages deployed as part of the Feature, ASCX files, and DLL and RESX files.

Event Handler Feature

SharePoint Event Handler is a program that enhances and adds functionality throughout SharePoint List, List Items or Sites. Event Feature can be deployed to new or existing sites by using Features. SharePoint Object Model provides several event classes that can target event handlers to List, List Item or Sites.

Synchronous and Asynchronous Events

In addition to asynchronous events, SharePoint Server 2007 introduces synchronous events i.e. events that activate before the action occurs. Synchronous events can trap an item, document library or site before it is deleted. Synchronous events removed the ability for users to delete an item from the document library or event restricts users to delete columns from the document library.
SharePoint Object Model exposes several event classes inherited from Microsoft.SharePoint assembly. There are three main event classes:
  • SPItemEventReceiver
  • SPListEventReceiver
  • SPWebEventReceiver
Each class includes both synchronous and asynchronous methods to work with Item, List or Web Level. In this article, I will demonstrate how to hook an ItemDeleting, FieldDeleting or SiteDeleting Event to restrict users from deleting an item from the document library or from deleting a column from the document library.

SPItemEventReceiver

By overriding a member of the SPItemEventReceiver class, developers can restrict users from deleting, updating an Item in a List. Some of the important SPItemEventReceiver class members are described below:
Event Event Type Description
ItemAdded Asynchronous After an Item added in a list
ItemAdding Synchronous Before an Item added in a list
ItemAttachmentAdded Asynchronous After an attachment added from a list item
ItemAttachmentAdding Synchronous Before an attachment added from a list item
ItemAttachmentDeleted Asynchronous After attachment deleted from a list item
ItemAttachmentDeleting Synchronous Before attachment deleted from a list item
ItemCheckedOut Asynchronous After an item checked-In in a list
ItemCheckingOut Synchronous Before an item is checked out in a list
ItemCheckedIn Asynchronous After an item is checked-In in a list
ItemCheckingIn Synchronous Before an item is checked-In in a list
ItemDeleted Asynchronous After an item is deleted from a list
ItemDeleting Synchronous Before an item is deleted from a list
ItemUpdated Asynchronous After an item is updated in a list
ItemUpdating Synchronous Before an item is updated in a list
For the demonstration, I am using a synchronous event i.e. ItemDeleting, which restricts users from deleting an item in a list (document library). You can invoke this event with any type of list of document library by specifying the ListTemplateId attribute in a Feature Schema file e.g. ItemEventReceiver.xml.
See the screenshot below of ItemEventReceiver.cs and ItemEventReceiver.xml for defining the ListTemplateId and Assembly.
ItemDeletingEvent.JPG
ItemEventReceiver.cs class

ItemDeletingEvent.JPG
ItemEventReceiver.xml file
The following table shows the default list template integer IDs that you can use in defining the template ID for event handlers.
List Template Id List Template
100 Generic list
101 Document library
102 Survey
103 Links list
104 Announcements list
105 Contacts list
106 Events list
107 Tasks list
108 Discussion board
109 Picture library
110 Data sources
111 Site template gallery
113 Web Part gallery
114 List template gallery
115 XML Form library
120 Custom grid for a list
200 Meeting Series list
201 Meeting Agenda list
202 Meeting Attendees list
204 Meeting Decisions list
207 Meeting Objectives list
210 Meeting text box
211 Meeting Things To Bring list
212 Meeting Workspace Pages list
300 Portal Sites list
1100 Issue tracking
2002 Personal document library
2003 Private document library

SPListEventReceiver

By overriding a member of the SPListEventReceiver class, developers can restrict users from deleting, updating a list from a Site. Some of the important SPListEventReceiver class members are described below.
Event Event Type Description
FieldAdded Asynchronous After a document is added in a List
(Document Library)
FieldAdding Synchronous Before a document is added in a List
(Document Library)
FieldDeleted Asynchronous After a document is deleted from a list
(Document Library)
FieldDeleting Synchronous Before a document is deleted from a list
(Document Library)
FieldUpdated Asynchronous After a document is updated in a list
(Document Library)
FieldUpdating Synchronous Before a document is updated in a list
(Document Library)
For the demonstration, I am using a synchronous event i.e. FieldDeleting, which restricts users from deleting a document from a list (Document Library). In this case, I am again specifying ListTemplateId = 101 for Document Library in a ListEventReceiver.xml file.

SPWebEventReceiver

By overriding a member of the SPWebEventReceiver class, developers can restrict users from deleting a site from a site collection or even completely delete a site collection. Some of the important SPWebEventReceiver class members are described below:
Event Event Type Description
SiteDeleted Asynchronous After a site collection has been deleted
SiteDeleting Synchronous Before a site collection is being deleted
WebDeleted Asynchronous After a web site has been deleted
WebDeleting Synchronous Before a web site is being deleted
For the demonstration, I am using a synchronous event i.e. WebDeleting, which restricts users from deleting a web site from a site collection.

Building the Solution

We need Visual Studio 2005 to create a solution for providing the required functionality.
The steps required to create an event handler for SharePoint Sever application are described below:
  • Create a C#.NET Class Library Solution in Visual Studio .NET 2005 and give a name, such as EventHand<code>lerFeature
  • On the Project Menu, choose Add Reference to Open Reference dialog box
  • Scroll down to Windows SharePoint Services and click the references the Microsoft.SharePoint.dll
  • Create a new folder inside Project Solution and give a name such as Features
  • Create three folders inside Features folder and give names such as ItemEventReceiver, ListEventReceiver and WebEventReceiver folders.
  • Create Feature.XML and feature schema file for ItemEventReceiver folder.

Attributes of Feature.XML File

Some of the attributes of Feature Tag are described below:
Attribute Value Description
ID GUID Contains the globally unique identifier (GUID) for the Feature.
Title Text Returns the title of the Feature. Limited to 255 characters.
Scope Farm/WebApplication/Site/Web Can contain one of the following values: Farm (farm), WebApplication (Web application), Site (site collection), and Web (Web site).
Hidden True/False This attribute equals FALSE by default.
AlwaysForceInstall True/False Optional Boolean. TRUE if the Feature is installed by force during installation even if the Feature is already installed. For example, if set to TRUE, Feature installation callouts will always fire anytime a user tries to install the Feature (even if it is already installed) by using either the scanforfeatures or installfeature command-line operation. This attribute equals FALSE by default. The AlwaysForceInstall attribute affects Features of all scopes.
See screenshot below of Feature.XML file.
FeatureXML.JPG
  • Repeat the above step from ListEventReceiver and WebEventReceiver folders
  • Create a new C#.NET class and give a name, such as ItemEventReceiver.cs class. Add Microsoft.SharePoint namespace and inherit this class from SPItemEventReceiver class in order to override ItemDeleting member for restricting users from deleting an Item from a list or document library
  • Repeat the above step and create two more classes and give names, such as ListEventReceiver.cs and WebEventReceiver.cs
  • Build the Solution
  • Sign the solution by using SN utility of .NET command prompt or specifying the Sign Assembly name in the solution properties.
Note: Complete source code of solution and package file is attached with this article.

Packaging the Features

In SharePoint Server 2007, Solutions are used to package and deploy Features, Site Definitions, Web Parts, Template Files, Assemblies and Code Access Security (CAS) policies to SharePoint front-end servers.
Steps for creating a Solution Package are described below:
  • Create Manifest.XML file as part of the same project, which contains information Solution and path of feature files as part of the overall solution.
  • Create the Diamond Discovery File i.e. DDF file, which contains information to compress files into a CAB file.
  • In the windows command prompt, run MakeCab.Exe on the DDF file to generate the WSP file. Note: MakeCab.Exe file can be downloaded from the Microsoft Site and should be copied into the same directory containing the Visual Studio Project Files.
  • See screenshot below to make WSP file by using MakeCab.EXE command line utility.
Make WSP Cabinet File.JPG

Deploying the Features

Steps for deploying a Solution Package are described below:
  • Use the STSADM.EXE command line tool to add WSP file into the SharePoint Solution Store.
add solution.JPG
  • Navigate to SharePoint Central Administration Page.
  • Click "Operation" Tab and Select "Solution Management" to see the list of solutions deployment in a Farm.
pg1.JPG
See screen below for a list of solutions deployed in a farm.
pg2.JPG
  • Click EventHandlerFeature link to deploy the solution to specified Web Application.
  • Click "Deploy Solution" to deploy the EventHandlerFeature Solution to Web Application. See screenshot below.
pg3.JPG
  • Select "Web Application" and Click "OK" to deploy the solution. See screenshot below for details.
pg3.JPG

Activating the Solution

  • Now navigate Site Settings and Select Site Features of the required web site.
  • Select the desired Site Feature and click "Activate" button to activate the Feature. See screenshot below for details.
pg6.JPG
  • You can use STSADM command line utility to activate a feature on a particular web site by specifying the URL.
Activate.JPG

Testing the Solution

  • ItemEventResource Feature:
Navigate to a Document Library in a Site, Where you have activated ItemEventResource feature.
    • Select a document and click "Delete" to delete the document.
    • SharePoint will generate an error page stating that you cannot delete an item from document library.
    • De-Activate the feature and try to delete the same document from the library. Now, in this instance, you can successfully delete the document.
pg8.JPG
  • ListEventResource Feature:
Navigate to a Document Library in a Site, Where you have activated ListEventResource feature.
    • Select "Settings" and click "Document Library Settings" to navigate the document library settings page.
    • Select any column and delete a column from the Document Library.
    • SharePoint will generate an error page stating that you cannot delete columns from this Document Library.
pg7.JPG
  • WebEventResource Feature:
Navigate to a Site in a Web Application, Where you have activated WebEventResource feature.
    • Click Site Action and Settings.
    • Click "Delete this Site" to delete the site.
    • SharePoint will generate an error page stating that you cannot delete this Site from the Web Application.
      Note: Please first try this solution to a testing environment in order to avoid any catastrophe.

Deactivating and Uninstalling the Solution

You can choose to turn deactivate a particular feature on your site or web application, or you can choose to uninstall a feature, which completely removes the feature from your SharePoint deployment. Features can be deactivated either through the administrative user interface or by using the STSADM.EXE command-line tool.
  • Deactivating the Feature by administrative user interface:
    • Browse the site where you want to deactivate the feature, Click Site Actions, and under Site Administration, click Site Features.
    • On the Site features page, locate the Feature you want to deactivate and click the Deactivate button to deactivate the Feature
deactivate.JPG
  • Deactivating the feature by using the STSADM.EXE command-line utility:
    • Open the Windows command-line tool and type the following command: STSADM.EXE –o deactivatefeature –name ItemEventReceiver –url http://mtech.litwareinc.com/
  • Uninstalling the Feature by using the STSADM.EXE command-line utility
    • Open the Windows command-line tool and type the following command: STSADM.EXE –o uninstallfeature –name ItemEventReceiver –force
Note: Files deployed as part of the Feature, such as ASPX, ASCX files are not removed when a Feature is uninstalled.

Print this post

No comments: