Adding an Application Page to an Event Receiver

Well, we know how to write an Event Receiver, we know how to customize the error message that is displayed to the user but is there a way to customize the error page that is displayed? The answer is—YES. Visual Studio provides a very easy way to customize these error pages. In the following recipe, we will find out how it is done.

Getting ready

You should have successfully completed the previous two recipes to follow this.

How to do it...

1. If you have closed Visual Studio IDE, launch it as an administrator.

2. Open the previously created ListItemEventReceiver solution.

3. Right-click on the project and select Add New Item to add an Application Page as shown in the following screenshot:

   

4. Name it EventReceiverErrorPage.aspx and click Add. This will generate an .aspx page underneath a folder called Layouts. This is a SharePoint mapped folder hence the green circular icon next to this folder. Underneath this mapped folder a subfolder with the same name as the project (in our case ListItemEventReceiver) is created and this is where you will find you're newly created Application Page.

5. Open up the .aspx page and add a label under the section:

   <asp:Content ID="Main" ContentPlaceHolderID="PlaceHolderMain" runat="server">

6. Change the ID of the label to "lblErrMsg" and clear out the Text attribute. Your ASPX mark-up should be as follows:

   <%@ Assembly Name="$SharePoint.Project.AssemblyFullName$" %>
   <%@ Import Namespace="Microsoft.SharePoint.ApplicationPages" %>
   <%@ Register Tagprefix="SharePoint" Namespace="Microsoft.SharePoint.WebControls" Assembly="Microsoft.SharePoint, Version=14.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" %>
   <%@ Register Tagprefix="Utilities" Namespace="Microsoft.SharePoint.Utilities" Assembly="Microsoft.SharePoint, Version=14.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" %>
   <%@ Register Tagprefix="asp" Namespace="System.Web.UI" Assembly="System.Web.Extensions, Version=3.5.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" %>
   <%@ Import Namespace="Microsoft.SharePoint" %>
   <%@ Assembly Name="Microsoft.Web.CommandUI, Version=14.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" %>
   <%@ Page Language="C#" AutoEventWireup="true" CodeBehind="EventReceiverErrorPage.aspx.cs" Inherits="ListItemEventReceiver.Layouts.ListItemEventReceiver.EventReceiverErrorPage" DynamicMasterPageFile="~masterurl/default.master" %>
   
   <asp:Content ID="PageHead" ContentPlaceHolderID="PlaceHolderAdditionalPageHead" runat="server">
   
   </asp:Content>
   
   <asp:Content ID="Main" ContentPlaceHolderID="PlaceHolderMain" runat="server">
       <asp:Label ID="lblErrMsg" runat="server" Text=""></asp:Label>
   </asp:Content>
   
   <asp:Content ID="PageTitle" ContentPlaceHolderID="PlaceHolderPageTitle" runat="server">
   Event Receiver Error
   </asp:Content>
   
   <asp:Content ID="PageTitleInTitleArea" ContentPlaceHolderID="PlaceHolderPageTitleInTitleArea" runat="server" >
   Event Receiver Error
   </asp:Content>

7. Right-click anywhere on the ASPX page and select View Code to open the EventReceiverErrorPage.apsx.cs file in order to wire the label created previously to the error message. The code inside the Page_Load method should be as follows:

   protected void Page_Load(object sender, EventArgs e)
     {
            string sErrMsg = Request.Params["ErrMsg"];
            lblErrMsg.Text = sErrMsg;
     }

8. Now we need to wire this page in our Event Receiver whenever there is an error. To do that, we will open EventReceiver1.cs file and add the following code after the line that says properties.Cancel = true:.

   properties.Status = SPEventReceiverStatus.CancelWithRedirectUrl;
   properties.RedirectUrl = string.Format("/_layouts/ListItemEventReceiver/EventReceiverErrorPage.aspx?ErrMsg={0}", sErrMsg);

9. Enter a new contact with an improper phone format for the Business Phone field. You should see your custom error screen and custom error message as follows:

   

How it works...

As indicated in the previous recipe, the properties object can be set with different statuses. One such status is CancelWithRedirectUrl. This directs SharePoint to look at another property called RedirectUrl. This is the property where you set up your custom URL and send the error message to it as a query parameter.

When you added the Application Page to the project, we saw a mapped folder called Layouts getting added. Mapped folders are file system locations on the SharePoint server. The Layouts folder can be found at: "\Program Files\Common Files\Microsoft Shared\Web Server Extensions\14\TEMPLATE". Generally this location is referred to as Root. Some SharePoint developers refer to this location as Hive. Any subfolders that are added underneath these mapped folders will be created on the disk on each of the SharePoint servers in the farm.

Whenever you create a web application in SharePoint, all these mapped folders are mapped for the web application. The layouts mapped folder is mapped as _layouts and CONTROLTEMPLATES as _controltemplates and so on. So all the site collections and sites in the web application can access these mapped folders through their relative paths. This is the reason why we qualified the link to our Application Page with /_layouts/.

There's more...

Visual Studio follows a good development model of creating subfolders underneath mapped folders when you need to add your custom resources. This way you do not overwrite any of the OOB SharePoint components with the same name. Also, do not try to change the files in the Root. This will affect the entire farm.

See also

• Validating data when an item is added to a list recipe

• Adding a custom error message to the Event Receiver recipe

• Working with List Event Receiver recipe