Scheduler

Exception Handling

The exception handling API in DotNetNuke provides a framework for handling exceptions uniformly and elegantly. Exception handling primarily uses four methods, most of which have several overloaded methods. Through these methods, developers can gracefully handle exceptions, log the exception trace and context, and display a user-friendly message to the end user.

The Exception Handling API

The exception handling API lives under the DotNetNuke.Services.Exceptions namespace. Table 8-2 lists the classes that comprise the Exception Handling API.

Table 8-2: Exception Handling Classes

Class	Description
BasePortalException	Inherits from System.Exception and contains many other properties specific to the portal application.
ErrorContainer	Generates formatting for the error message that will be displayed in the web browser.
ExceptionInfo	Stores information from the stack trace.
Exceptions	Contains most of the methods that are used in custom modules. It contains the methods necessary to process each type of portal exception.
ModuleLoadException	An exception type for exceptions thrown within portal modules. It inherits from BasePortalException.
PageLoadException	An exception type for exceptions thrown within pages.
SchedulerException	An exception type for exceptions thrown within the Scheduling Provider. It also inherits from BasePortalException.

The Exceptions Class

Although there are many classes in the exception handling namespace, the primary class that module developers deal with regularly is the Exceptions class. This class contains all of the methods necessary to gracefully handle exceptions in DotNetNuke. The most widely used method for exception handling is DotNetNuke.Services.Exceptions.ProcessModuleLoadException().

ProcessModuleLoadException Method

The ProcessModuleLoadException method serves two primary functions: to log the exceptions that are thrown from within a module to the Logging Provider, and to display a friendly error message in place of the module that threw the exception. The friendly error message is displayed only if the host option Use Custom Error Messages is enabled on the Host Settings page (see Chapter 5).

ProcessModuleLoadException has seven overloaded methods:

• To process an exception that occurs in a portal module, use the following method. If the Custom Error Messages option has been enabled in Host Settings, this method will also handle displaying a user-friendly error message to the client browser:

   Public Sub ProcessModuleLoadException(ByVal ctrlModule As _ Entities.Modules.PortalModuleBase, ByVal exc As Exception) 

  Parameter	Type	Description
  ctrlModule	PortalModuleBase	Portal module object.
  exc	Exception	Exception that was thrown.

• This method is the same as the previous one, although it provides the capability to suppress the error message from being displayed on the client browser:

   Public Sub ProcessModuleLoadException(ByVal ctrlModule As _ Entities.Modules.PortalModuleBase, ByVal exc As Exception, ByVal _ DisplayErrorMessage As Boolean) 

  Parameter	Type	Description
  ctrlModule	PortalModuleBase	Portal module object.
  exc	Exception	Exception that was thrown.
  DisplayErrorMessage	Boolean	Indicates whether the portal should render an error message to the client browser.

• This is the same as the previous method; however, it adds the capability to provide a custom friendly message to the client browser:

   Public Sub ProcessModuleLoadException(ByVal FriendlyMessage As String, ByVal _ ctrlModule As Entities.Modules.PortalModuleBase, ByVal exc As Exception, _ ByVal DisplayErrorMessage As Boolean) 

  Parameter	Type	Description
  FriendlyMessage	String	Friendly message to display to the client browser.
  ctrlModule	PortalModuleBase	Portal module object.
  exc	Exception	Exception that was thrown.
  DisplayErrorMessage	Boolean	Indicates whether the portal should render an error message to the client browser.

• Use the following overloaded method if you are handling exceptions in a control that isn't directly in a portal module. For instance, if your portal module uses a server control, you can use this method to handle exceptions within that server control. It displays a friendly error message if custom error messages are enabled:

   Public Sub ProcessModuleLoadException(ByVal FriendlyMessage As String, _ ByVal UserCtrl As Control, ByVal exc As Exception) 

  Parameter	Type	Description
  FriendlyMessage	String	Friendly message to display to the client browser.
  UserCtrl	Control	The control. It can be anything that inherits from System.Web.UI.Control.
  exc	Exception	Exception that was thrown.

• This is the same as the previous method; however, it adds the capability to specify whether to display an error message to the client browser (the Host Settings option to Use Custom Error Messages takes precedence over this value):

   Public Sub ProcessModuleLoadException(ByVal FriendlyMessage As String, _ ByVal ctrlModule As Control, ByVal exc As Exception, _ ByVal DisplayErrorMessage As Boolean) 

  Parameter	Type	Description
  FriendlyMessage	String	Friendly message to display to the client browser.
  ctrlModule	Control	The control. It can be anything that inherits from System.Web.UI.Control.
  exc	Exception	Exception that was thrown.
  DisplayErrorMessage	Boolean	Indicates whether the portal should render an error message to the client browser.

• This is a simple method that has only two parameters. It displays a generic error message to the client browser if custom error messages are enabled:

   Public Sub ProcessModuleLoadException(ByVal UserCtrl As Control, _ ByVal exc As Exception) 

  Parameter	Type	Description
  UserCtrl	Control	The control. It can be anything that inherits from System.Web.UI.Control.
  exc	Exception	Exception that was thrown.

• This is the same as the previous method except it provides the capability to suppress the error message that is displayed in the client browser (the Host Settings option to Use Custom Error Messages takes precedence over this value):

   Public Sub ProcessModuleLoadException(ByVal UserCtrl As Control, _ ByVal exc As Exception, ByVal DisplayErrorMessage As Boolean) 

  Parameter	Type	Description
  UserCtrl	Control	The control. It can be anything that inherits from System.Web.UI.Control.
  exc	Exception	Exception that was thrown.
  DisplayErrorMessage	Boolean	Indicates whether the portal should render an error message to the client browser.

ProcessPageLoadException Method

Similar to the ProcessModuleLoadException method, the ProcessPageLoadException method serves two primary functions: to log the exceptions thrown from outside of a module to the Logging Provider, and to display a friendly error message on the page. The friendly error message will only be displayed if the host option Use Custom Error Messages is enabled on the Host Settings page (see Chapter 5).

ProcessPageLoadException has two overloaded methods:

• To process an exception that occurs in an ASPX file or in logic outside of a portal module, use the following overloaded method. If the Use Custom Error Messages option has been enabled in Host Settings, this method also handles displaying a user-friendly error message to the client browser:

   Public Sub ProcessPageLoadException(ByVal exc As Exception) 

  Parameter	Type	Description
  exc	Exception	Exception that was thrown.

• This is the same as the previous method; however, you must send in the URL parameter to redirect the request after logging the exception:

   Public Sub ProcessPageLoadException(ByVal exc As Exception, _ ByVal URL As String) 

  Parameter	Type	Description
  exc	Exception	Exception that was thrown.
  URL	String	URL to redirect the request to.

LogException Method

The LogException method is used for adding exceptions to the log. It does not handle displaying any type of friendly message to the user. Instead, it simply logs the error without notifying the client browser of a problem. LogException has four overloaded methods:

• To log an exception thrown from a module, use the following overloaded method:

   Public Sub LogException(ByVal exc As ModuleLoadException) 

  Parameter	Type	Description
  exc	ModuleLoadException	Exception that was thrown.

• To log an exception thrown from a page or other logic outside of a module, use the following overloaded method:

   Public Sub LogException(ByVal exc As PageLoadException) 

  Parameter	Type	Description
  exc	PageLoadException	Exception that was thrown.

• To log an exception thrown from within a Scheduling Provider Task, use the following overloaded method:

   Public Sub LogException(ByVal exc As SchedulerException) 

  Parameter	Type	Description
  Exc	SchedulerException	Exception that was thrown.

• If you need to log an exception of another type, use the following overloaded method:

   Public Sub LogException(ByVal exc As Exception) 

  Parameter	Type	Description
  exc	Exception	Exception that was thrown.

ProcessSchedulerException Method

The ProcessSchedulerException method is used to log exceptions thrown from within a scheduled task. It simply logs the error.

To log an exception thrown from a scheduled task, use the following overloaded method:

     Public Sub LogException(ByVal exc As ModuleLoadException) 

Parameter	Type	Description
exc	ModuleLoadException	Exception that was thrown.

The exception handling API abstracts developers from the complexity of logging exceptions and presenting error messages gracefully. It provides several powerful methods that handle all of the logic involved in working with the Logging Provider and the presentation layer. The next section covers the various interfaces that module developers can take advantage of to bring more core features to life in their modules.