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.




Professional DotNetNuke 4.0 (c) Open Source Web Application Framework for ASP. NET 4.0
Professional DotNetNuke 4: Open Source Web Application Framework for ASP.NET 2.0 (Programmer to Programmer)
ISBN: 0471788163
EAN: 2147483647
Year: 2006
Pages: 182

Similar book on Amazon

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net