Entering Configuration Information

  • Article

These procedures explain how to configure the Exception Handling Application Block. For information about using the configuration tools, see Using the Configuration Tools. For details of the schema for the Exception Handling Application Block configuration, see Source Schema for the Exception Handling Application Block. You can also configure the block in code by using an alternate configuration source. For more information, see Advanced Configuration Scenarios and Using the Fluent Configuration API.

To add the Exception Handling Application Block

  1. Open your configuration file in the configuration editor. For more information, see Configuring Enterprise Library.
  2. Open the Blocks menu and then click Add Exception Handling Settings.
  3. This creates an Exception Handling Settings section with one exception handling policy that by default is called Policy, and a single item named All Exceptions in the Exception Types column that defines all exceptions of type System.Exception or that inherit the System.Exception class.
  4. To edit the properties of the Exception Handling Settings section, click the chevron arrow the right of the Exception Handling Settings heading.
  5. (Optional) If you want to encrypt the configuration, make a selection from the Protection Provider drop-down list. You can select the RsaProtectedConfigurationProvider or the DataProtectedConfigurationProvider. See Encrypting Configuration Data for information about the restrictions on using the RsaProtectedConfigurationProvider.
  6. (Optional) If you want to run your application in partial trust mode, change the Require Permission property to False. The default is True.

To configure an exception handling policy

  1. To add an exception handling policy, click the plus sign icon in the Policies column and click Add Policy. This adds a new exception handling policy item. Click the expander arrow on the left of the policy heading if the properties are not visible.
  2. (Optional) Rename the policy. In the Name text box, type the required policy name.
  3. To add an exception type to a policy, right-click the policy item and click Add Exception Type to display the type selector dialog.
  4. Select the exception type in the type selector dialog box. To filter the list, type the filter string in the Filter edit box. For example, type "string" to filter for all classes containing the word string. If the type you want is not listed, click Add from File or Add from GAC (from the global assembly cache) and find the assembly containing the type you want, and then click OK. This creates the new policy and a default All Exceptions item.
  5. Click the expander arrow to the left on the new All Exceptions node in the Exception Types column to display the properties if they are not visible.
  6. Select the Post handling action you want. The post-handling action determines what action will occur after the exception handling chain completes. By default, the post-handling action is set to NotifyRethrow. In general, when you use the Process method, you will configure the exception handling policy with a post-handling action of ThrowNewException unless you want your code to continue to execute after the block handles the exception. Valid values are the following:
    • NotifyRethrow. The block executes all handlers for this exception and returns true to the application at the point at which the policy was invoked. Applications checking this value re-throw the original exception. However, if you use the Process method you cannot detect the value returned by the Exception Handling Application Block. Internally, the Process method calls the HandleException method, and throws the exception if this method returns true. Therefore, typically your code will just throw any exception that is raised.
    • ThrowNewException. The block executes all handlers for this exception and throws the exception that exists after the final handler runs. However, if you use the overload of the HandleException method that takes an out parameter that returns the final exception from the handlers, it does not automatically throw the exception; you must do this in your code.
    • None. The block executes all handlers for this exception and returns false to the application at the point at which the policy method was invoked. Applications checking this value resume execution.
  7. To add additional exception types to the policy, repeat steps 3 to 6.
  8. To add an exception handler, right click the All Exceptions item or an exception item you added, point to Add Handlers, and then click the exception handler type that you want:
    • Replace exception handler. This exception handler replaces one exception with another.
    • Wrap exception handler. This exception handler wraps the exception that occurred with another exception.
    • Logging exception handler. This exception handler formats exception information and uses the Logging Application Block to log exception information. The Logging Application Block is automatically added to the application configuration when you select a logging handler. For more information, see The Logging Application Block.
    • Fault Contract exception handler. This exception handler is designed for use at Windows Communication Foundation (WCF) service boundaries, and generates a new Fault Contract from the exception.
    • Custom exception handler. This option allows you to configure custom exception handlers. A custom handler is a type that implements the IExceptionHandler interface and has a ConfigurationElementType of CustomHandlerData. Click Add from File in the type selector to add a custom handler that is located in a separate assembly.
  9. To add additional exception handlers to the policy, repeat step 8.
  10. If required, change the order of the exception handlers by right-clicking the handler item heading and clicking either Move Up or Move Down. Handlers are executed in the order you specify. Typically, you will place a Logging handler first in the list, followed by a Wrap handler or a Replace Handler.
  11. See the following section of this topic for details of how to configure exception handlers.

Configuring Exception Handlers

After you add an exception handler to the exception, you can configure it. These procedures explain how to configure the properties of the Replace, Wrap, Logging, Fault Contract, and Custom exception handlers.

To configure a Replace exception handler

  1. If the properties of the exception handler are not visible, click the expander arrow to the right of the exception handler heading.
  2. (Optional) Edit the Name of the handler if required.
  3. Enter the Exception Message. This is the text of the message to be used for the replacement exception. This property is optional.
  4. Select the Replace Exception Type. This is the fully qualified name of the exception type that will replace the original exception. Click the ellipses (...) button and use the type selector to select the required type.
  5. If you wish to load a localized exception message from a resource in your project, enter the name of the resource string in the Message Resource Name property. Then click the ellipses (...) button in the Message Resource Type property and use the type selector to select the resource file containing the message strings.

To configure a Wrap exception handler

  1. If the properties of the exception handler are not visible, click the expander arrow to the right of the exception handler heading.
  2. (Optional) Edit the Name of the handler if required.
  3. Enter the Exception Message. This is the text of the message to be used for the exception that will wrap the original exception. This property is optional.
  4. Select the Wrap Exception Type. This is the fully qualified name of the exception type that will wrap the original exception. Click the ellipses (...) button and use the type selector to select the required type.
  5. If you wish to load a localized exception message from a resource in your project, enter the name of the resource string in the Message Resource Name property. Then click the ellipses (...) button in the Message Resource Type property and use the type selector to select the resource file containing the message strings.

To configure a Logging exception handler

  1. If the properties of the exception handler are not visible, click the expander arrow to the right of the exception handler heading.
  2. (Optional) Edit the Name of the handler if required.
  3. Edit the Event ID. This is the ID number of the event that will be logged. The default value is 100.
  4. (Optional) Specify the Formatter Type. This is the fully qualified name of the formatter used to format the exception information before it is logged. The default is TextExceptionFormatter. To use a different formatter or a custom formatter, click the ellipsis button (…) and use the type selector to select the formatter you require. Enterprise Library includes an XmlExceptionFormatter type that you can use to format messages as XML. If you are using the Visual Studio integrated configuration editor and you do not see the formatter type you require in the list, you must add a reference to the assembly containing that formatter to your project.
  5. (Optional) Edit the Logging Category. This is the name of the logging category that the event is assigned to, as defined in the Logging Application Block (which is added to your configuration automatically when you add a Logging exception handler). The default name is General. If you create a new category in the Logging Application Block, you can select this category in the drop-down list for the Logging Category property. For information about how to configure the Logging Application Block, see Entering Configuration Information.
  6. (Optional) Edit the Priority. This is the priority of the log message. The Logging Application Block can be configured to filter log messages based on their priority.
  7. (Optional) Edit the Severity. This is the severity of the event. The default value is Error. To select another level of severity, click an entry in the drop-down list. The other choices are Critical, Warning, Information, Verbose, Start, Stop, Suspend, Resume, and Transfer.
  8. (Optional) Edit the Title. This is the title of the log entry. The default value is Enterprise Library Exception Handling.

To configure a Fault Contract exception handler

  1. If the properties of the exception handler are not visible, click the expander arrow to the right of the exception handler heading.
  2. (Optional) Edit the Name of the handler if required.
  3. Enter the Exception Message. This is the text of the message to be used for the exception that will be returned to the client.
  4. Specify the Fault Contract Type. This is the type of the WCF Fault Contract you want to return when an exception occurs. The Fault Contract exception handler generates a new instance of this type, extracts the values from the properties of the exception that you pass to the block, and sets the values of the new fault contract instance to the values extracted from the original exception.
  5. The Fault Contract exception handler can use mappings you specify between the exception property names and the names of the properties exposed by the fault contract to assign the exception values to the appropriate properties. If you do not specify a mapping, it matches the source and target properties that have the same name. If you need to map the properties in the fault contract to the properties of the exception type because the property names differ, click the plus sign in the Property Mappings property and enter the mappings you require. To remove a mapping, click the cross icon.

For more information about configuring a fault contract exception handler, see Shielding Exceptions at WCF Service Boundaries.

To configure a custom exception handler

  1. If the properties of the exception handler are not visible, click the expander arrow to the right of the exception handler heading.
  2. In the Attributes property, add any key/value pairs required to configure the handler. As you type a key, the configuration tool adds a new row. To remove a key/value pair, click the cross icon.