Architecture of an Application Block in Enterprise Library
The client code calls into the ProviderBase Factory class with the Create ProviderBase method. The ProviderBase Factory then calls the ProviderBase InstanceFactory class. This class calls the Enterprise Library core, which examines the I ProviderBase interface for the attribute that tells it what sort of custom factory to use. It creates an instance of that class and uses it to discover the appropriate configuration object. In this case, the correct object is the Provider Data class. The core then examines the Provider Data class for the Assembler attribute that tells it which assembler to build. It builds the assembler and passes it the Provider Data class. The assembler constructs an instance of the Provider class.
Application Block Software Factory Generated Files
Application Block Software Factory produces application blocks that have a run-time component and a design-time component. The run-time component implements the application block’s functionality. The application block also provides the configuration schema, which defines the application block’s behavior. The design-time component makes it possible to display this information in the configuration tools. Either of these tools allows you to read an application block’s current configuration, to change it and to store it. Most of an application block’s functionality and configuration information is contained in classes that implement the providers.
The Run-Time Component
Table 1 lists the most relevant run-time classes created by the Application Block Software Factory that implement a provider’s functionality.
Table 1: Run-time component classes for functionality
Class name
Description
Provider
This class is an implementation of the provider base class. The Create New Provider (Typed) or Create New Provider (Untyped) recipe creates this file.
ProviderBase Factory
This is a static class that has a Create Provider method. This method allows users to create instances of the provider. The New Provider Factory and Base recipe creates this file.
ProviderBase CustomFactory
This class finds the correct configuration information for the provider that is being instantiated and returns it to the Enterprise Library core. The New Provider Factory and Base recipe creates this file.
ProviderBase InstanceFactory
This is the entry point into the Enterprise Library core. The New Provider Factory and Base recipe creates this file.
ProviderBase
The provider base class that implements the I ProviderBase interface. Provider implementations derive from this class
I ProviderBase
The interface that the provider base class implements. The New Provider Factory and Base recipe creates this file.
Table 2 lists the run-time classes that contain an application block or a provider’s configuration information.
Table 2: Run-time component classes for configuration information
Class name
Description
ApplicationBlock Settings
This class defines the application block’s configuration information. The design-time counterpart of this file is ApplicationBlock SettingsNode class. The Create Application Block recipe creates this file.
ProviderBase DataRetriever
This is a helper class that is responsible for retrieving the default instance name from the configuration.
ProviderBase Data
This class defines the base provider class’s configuration information. The design-time counterpart is the ProviderBase Node class. The New Provider Factory and Base recipe creates this file.
Provider Data
This class defines the provider’s configuration information. The design-time counterpart is the Provider Node class. The Create New Provider (Typed) or the Create New Provider (Untyped) recipe creates this file.
The Design-Time Component
The design-time component translates between the run-time configuration classes and the Configuration Console’s UI display. Table 3 lists the most relevant design-time files created by the Application Block Software Factory.
Table 3: Design-time component classes
Class name
Description
AddApplicationBlockSettingsNodeCommand
This class represents the menu command from the application that is used to add the configuration for the block (that is, “New, Data Access Application Block”)
ApplicationBlock SettingsNode
This class mirrors the properties in the ApplicationBlock SettingsNode. It represents the block’s top-level node in the configuration tool.
ApplicationBlock SettingsBuilder
This class translates the information in the UI configuration hierarchy nodes into run-time configuration classes. This is necessary in order to save the configuration information. The Create New Application Block recipe creates this file.
ApplicationBlock SettingsNodeBuilder
This class reads the configuration information by translating run-time configuration information into UI configuration hierarchy nodes. The Create New Application Block recipe creates this file.
CommandRegistrar
This class contains commands that place the nodes at the correct places in the configuration hierarchy. For example, the CreateSingleUICommand command ensures that a node only appears once. This class also associates the nodes with the correct UI commands such as Rename and Replace. The Create New Application Block recipe creates this file.
ConfigurationDesignManager
This class defines the UI commands, such as New, and the node maps for the configuration hierarchy. A node map defines the correspondence between the run-time configuration information and a UI node. It also contains the OpenCore method that reads the configuration information. The Create New Application Block recipe creates this file.
NodeMapRegistrar
This is a helper class that creates a mapping between nodes and configuration information. The Create New Application Block recipe creates this file.
ProviderBase Node
This class mirrors the properties in the ProviderBase Data class. It also defines characteristics such as the Configuration Console category for the property and whether or not the property is required. The New Provider Factory and Base recipe creates this file.
Provider Node
This class mirrors the properties in the Provider Data class. It also defines characteristics such as the Configuration Console category for the property and whether or not the property is required. The Create Design-Time Provider Node recipe creates this file.
Posted in: Software Programming C# and .NET| Tags: NET Enterprise Library Microsoft Enterprise Library application block provider ProviderBaseFactory CreateProviderBase IProviderBaseGlossary of Terms in Microsoft Enterprise Library
application block. A reusable software component that is designed to help developers with common enterprise development challenges. For example, the Enterprise Library includes a Data Access Application Block that developers can use to incorporate standard database functionality into their applications.
base node. The design-time counterpart of the run-time provider base class. Generally, the base node is defined in the BaseClassName Data class. The design-time project includes this class.
design - time project. The design-time project contains the files that make the application block and its providers visible and configurable in the Configuration Console and Visual Studio Configuration Editor.
default instance. The provider instance that the application block creates if the Create method has no type parameter. You define the default instance in the Create New Provider Factory and Base Wizard.
provider node. The design-time counterpart of the run-time provider implementation. The Application Block Software Factory creates a node when you complete the Create a Design-Time Provider Node wizard. Generally, the node is defined in the ProviderName Data class. The design-time project includes this class.
parent UI node. The node that contains the current node in the configuration hierarchy.
provider. A .NET object that supplies some functionality. The Enterprise Library includes many providers. For example, there is a provider that allows you to connect to a SQL database, execute commands, and retrieve results. The Application Block Software Factory creates a provider implementation when you complete the Create New Provider wizard. Generally, the ProviderName class defines the provider implementation. The run-time project includes this class. You can create either typed providers or untyped providers. Typed providers have strongly-typed their own strongly-typed configuration classes. Untyped providers use a generic name/value collection.
provider base class. The class from which provider implementations derive. The Application Block Software Factory creates a provider base class when you complete the Create New Provider Factory and Base wizard. Generally, the ProviderBaseClassName class defines the base class. The he run-time project includes this class.
provider library. A .NET Framework assembly with a corresponding Visual Studio project that contains a number of providers. These providers extend the functionality of an application block. This application block is included in a different assembly.
reference node. A node that the current node needs to correctly function. When you use the Application Block Software Factory to build a design-time project, you enter the value of a property’s reference node when you use the Create a Design-Time Provider Node wizard. Reference nodes appear as types in the dropdown list in the Configuration Console’s property pane. For example, in the Logging Application Block, if you have a trace listener that logs to a database, the reference node is the connection string for the database. If you are using a SQL database, you use the dropdown list to select System.Data.SqlClient as the type. You define a reference node when you define a provider’s properties in the Create New Provider wizard.
run-time configuration type. The class that contains the configuration information that the design time uses for the configuration tools.
typed provider. A provider that includes a ProviderName Data class. This class contains the run-time configuration information. This configuration information can be used in the design-time project so that the provider’s properties and values will appear in the configuration tools.
untyped provider. A provider that has a generic provider data class. This class uses a name/value collection that can apply to different types of providers.
Posted in: Software Programming C# and .NET| Tags: NET Enterprise Library Microsoft Enterprise Library application block base node default instance provider node provider reference node provider librarySecurity Application Block Dependencies of Enterprise Library
- Core library functionality. The Enterprise Library Core provides services, such as instrumentation and configuration, and is a shared dependency of all Enterprise Library application blocks. The core library functionality is contained in the assembly Microsoft.Practices.EnterpriseLibrary.Common.dll.
- The ObjectBuilder subsystem. The ObjectBuilder subsystem performs all of the repetitive and necessary tasks for creating and disposing of object instances, while still providing a high level of flexibility. Enterprise Library uses the ObjectBuilder subsystem for tasks such as injecting configuration into block classes and connecting instrumentation classes to application blocks. The ObjectBuilder subsystem is contained in the assembly Microsoft.Practices.ObjectBuilder.dll.Depending on the specific functionality you require from the Security Application Block, you may also require the following application block contained in the Enterprise Library:
- The Caching Application Block. The Security Application Block uses the Caching Application Block to cache security information and then retrieve it when required. You can replace the Caching Application Block with your own caching provider. Depending on how you configure the Caching Application Block, you may also require the Data Access Application Block. For more information, see the Caching Application Block documentation.
Security Application Block Documentation
Together with the introduction, the documentation contains the following topics:- Design of the Security Application Block. This topic explains the decisions that went into designing the application block and the rationale behind those decisions.
- Developing Applications with the Security Application Block. This topic explains how to download and install the application block so you can use it in your applications. It also is divided into several subsections. The first subsection, Entering Configuration Information, demonstrates how to configure the application block to perform common tasks. The next subsection, Key Scenarios, demonstrates how to use the application block to perform the most typical security operations.
- Extending and Modifying the Security Application Block. This topic explains how to extend the application block by creating your own providers and how to modify the source code.
- Deployment and Operations. This topic explains how to deploy and update the application block's assemblies and also contains information about configuration.
- QuickStarts. This topic explains how to install and configure the QuickStart applications and contains a series of walkthroughs that demonstrate how to incorporate common security operations into an application.
Displaying User-Friendly Messages
You may want to replace the message in the original exception with a more appropriate, user-friendly message. To do this, you must replace the original exception with another exception that has a more appropriate message associated with it. For example, exceptions that occur in the data access layer of an application can be replaced with an exception of type System.ApplicationException. This uses the message, "The application is unable to process your request at this time." This message is then displayed to the user.
Typical Goals
You want to display a user-friendly message when an exception occurs. Your application has code in its catch blocks similar to the following.
Note:
The code does not include implementations of the FormatException and Logger.Log methods. These methods represent typical ways to create and log a formatted exception message.
C# Copy Code
catch(SomeException e)
{
string formattedInfo = FormatException(e);
Logger.Log(formattedInfo);
throw e;
}
Visual Basic Copy Code
Catch e As SomeException
Dim formattedInfo As String = FormatException(e)
Logger.Log(formattedInfo)
Throw e
End Try
Solution
Use either a wrap handler or replace handler to create a new exception with the appropriate message.
QuickStart
For an extended example of how to use the Exception Handling Application Block to display a user-friendly message, see the QuickStart walkthrough, Walkthrough: Notifying the User.
Displaying User-Friendly Messages
The following procedure describes how to use the Exception Handling Block to display user-friendly messages.
To display user-friendly messages
Use the configuration tools to create an exception handling policy with the relevant exception types for your application. For more information, see Entering Configuration Information.
Configure the exception type. Specify the PostHandlingAction as ThrowNewException. The ThrowNewException action indicates that the application block will throw the exception that is returned from the last exception handler in the chain.
Add a new wrap exception handler for the specified exception types.
Configure the wrap exception handler with the new exception type and friendly message.
Modify your application code to execute the new policy when an exception occurs.C# Copy Code
try
{
// Run code.
}
catch(Exception ex)
{
bool rethrow = ExceptionPolicy.HandleException(ex, "Wrap Policy");
if (rethrow)
throw;
}
Visual Basic Copy Code
Try
' Run code.
Catch ex As Exception
Dim rethrow As Boolean = ExceptionPolicy.HandleException(ex, "Wrap Policy")
If (rethrow) Then
' throw original exception
Throw
End If
End Try
Usage Notes
If you use the Unity Integration approach to create instances of objects from the Exception Handling Application Block, you must use the non-static façade named ExceptionManager instead of the ExceptionPolicy class static façade.
Propagating an Exception in Enterprise Library
A frequently required exception-handling task is to allow the original exception to propagate up the call stack unchanged. You may want to do this because the handlers only perform actions such as logging that leave the exception unchanged or because other actions, such as wrapping and replacing, have been turned off. For example, a routine within a business logic component may log exceptions at the point where they are detected. It then propagates that exception to the caller for additional handling.
Typical Goals
You want to let an exception propagate up the call stack unchanged after the exception handler chain completes. Your application has code in its catch blocks similar to the following.
Note:
The code does not include the FormatException and Logger.Log methods. These methods represent typical application code to create and log a formatted exception message.
C# Copy Code
catch(SomeException e)
{
// Exception handling code to be done before propagating.
string formattedInfo = FormatException(e);
Logger.Log(e);
throw e;
}
Visual Basic Copy Code
Catch e As SomeException
' Exception handling code to be done before propagating.
Dim formattedInfo As String = FormatException(e)
Logger.Log(e)
Throw e
End Try
QuickStart
For an extended example of how to use the Exception Handling Application Block to propagate the original exception, see the QuickStart walkthrough, Walkthrough: Propagating the Original Exception.
Solution
Configure the relevant exception type to use NotifyRethrow as its PostHandlingAction.
Propagating an Exception
The following procedure describes how to use the Exception Handling Block to propagate an exception.
To propagate an exception
Create an exception handling policy with the relevant exception types for your application. For more information, see Entering Configuration Information.
Configure the exception type. Specify the PostHandlingAction as NotifyRethrow. This causes the application block to return true to the application from the call to the HandleException method.
Modify your application code to execute the new policy when an exception occurs.
Examine the return value from the HandleException call. If the return value is true, execute a throw statement, as shown in the following code example.C# Copy Code
try
{
// Run code.
}
catch(Exception ex)
{
bool rethrow = ExceptionPolicy.HandleException(ex, "Propagate Policy");
if (rethrow)
{
// Throw original exception.
throw;
}
}
Visual Basic Copy Code
Try
' Run code.
Catch ex As Exception
Dim rethrow As Boolean = ExceptionPolicy.HandleException(ex, "Propagate Policy")
If (rethrow) Then
' Throw original exception.
Throw
End If
End Try
Usage Notes
If you use the Unity Integration approach to create instances of objects from the Exception Handling Application Block, you must use the non-static façade named ExceptionManager instead of the ExceptionPolicy class static façade.
Wrapping an Exception
A frequently required exception-handling task is wrapping one exception with a different exception. Wrapping an exception creates a new exception of a defined type and sets the original exception as the InnerException object of the new exception. Use the wrapping capability in situations where the original exception type must be mapped to a new exception type for use by other tiers within the architecture of the application. You can encapsulate and interpret details of the underlying layer's original exception without losing any details about that exception. You can wrap the original exception either in an existing exception type or in a custom exception type that you create. The following explains a situation when you would want to wrap an exception:
- A business service named Update Customer calls a data layer service.
- The data layer service fails and throws an exception. This could be any one of many exceptions that indicate that the update failed. Some sets of these exceptions indicate that recovery may be possible with a retry (for example, if a record is locked) while others are non-recoverable (for example, if there is a concurrency violation or a dirty record).
- The exception handler maps and wraps these sets of exceptions into two exception types, RecoverableUpdateException and FatalUpdateException.
- The business service handles the exception based on the wrapping type and takes the appropriate action, even though it is insulated from detailed knowledge of the underlying failure.
Usage Notes
Consider the following information when you configure the application block to use a wrap handler:
- Typically, exceptions should be wrapped after they are logged in their original state.
- To help in the management and tracking of exceptions, the application block generates a HandlingInstanceID object that you can use to map to the original exception. To use the HandlingInstanceID, you must include the {handlingInstanceID} token in the exception message that is in the configuration file. The HandlingInstanceID is of type GUID. For more information, see Assisting Support Staff.
- If the post handling action is set to ThrowNewException, the exception thrown by the application block is the final exception that results from running the entire chain of handlers. For example, if the chain specifies that exception A is to be wrapped with exception B, and a later handler replaces exception B with exception C, the application block throws exception C when the post handling action is set to ThrowNewException.
- If the post handling action is set to NotifyRethrow, the application block returns true to the calling code. This allows the code to throw the original exception.
- Application code should always check the return value instead of assuming that it is the same value as the configured value. Even if the configuration data changes, if the application code checks the return value, the application code will function correctly and will not need to be modified.
- The exception type used to wrap another exception must have a constructor that accepts two parameters: a string and an exception object. This means that you must provide this constructor overload for all custom exception types that are used to wrap other exceptions.
- If you use the Unity Integration approach to create instances of objects from the Exception Handling Application Block, you must use the non-static façade named ExceptionManager instead of the ExceptionPolicy class static façade.
Logging an Exception
A frequently required exception-handling task is to log the information associated with the exception. The Exception Handling Application Block, in conjunction with the Logging Application Block, lets you log formatted exception information in locations specified in the configuration file. For example, client applications typically log application information in the event log, while a server component of an e-commerce application may log exceptions in a database.
Typical Goals
You want to log an exception that occurred in one of the application layers before any other exception handling occurs. Your application has code in its catch blocks similar to the following.
Note:
The code does not include the FormatException and Logger.Log methods. These methods represent typical application code to create a formatted exception message and write it to a log destination.
C#
Copy Code
catch(SomeException e)
{
string formattedInfo = FormatException(e);
Logger.Log(e);
throw e;
} Visual Basic
Copy Code
Catch e As SomeException Dim formattedInfo As String = FormatException(e) Logger.Log(e) Throw e End Try
Solution
Designate the logging handler as the first handler in your policy's exception handling chain. The Exception Handling Application Block includes the logging handler.
QuickStart
For an extended example of how to log an exception, see the QuickStart walkthrough, Walkthrough: Logging an Exception.
Using the Logging Handler
To use the logging handler, you must configure the application exception policies and the Logging Application Block. You must then modify your application to use the appropriate exception handling policy.
To configure the application exception policies
- Use the configuration tools to create an exception handling policy for your application layer. For more information, see Entering Configuration Information.
- Specify the exception types to be processed and logged.
- Add the logging handler as the first handler for each exception type.
- Configure the logging handler:
- Enter the event ID.
- Enter the logging categories.
- Select the severity.
- Enter the title of the log entry.
- Select the formatter type name.
- Enter the priority.
- Add any additional exception handlers to be invoked after the logging handler.
To configure the Logging Application Block
- Add the Logging Application Block to your application configuration (adding a logging handler will automatically add the Logging Application Block to your application configuration). For more information, see Adding Application Code in the documentation for The Logging Application Block.
- Configure the Logging Application Block.
Modify Your Application
Modify your application code to execute the new policy when an exception occurs. The following code demonstrates how to do this. Substitute the name "Logging Policy" with the name of your own policy.
C#
Copy Code
try
{
// Run code.
}
catch(Exception ex)
{
bool rethrow = ExceptionPolicy.HandleException(ex, "Logging Policy");
if (rethrow)
throw;
} Visual Basic
Copy Code
Try ' Run code. Catch ex As Exception Dim rethrow As Boolean = ExceptionPolicy.HandleException(ex, "Logging Policy") If (rethrow) Then Throw End If End Try
Usage Notes
Consider the following information when you configure the application block to use a logging handler:
- Exceptions can be logged any time during processing; they do not have to be logged at the beginning of the event handling sequence. For example, you can log an exception after it is wrapped or replaced.
- The Exception Handling Application Block provides a logging exception handler that depends on the Logging Application Block. You can also incorporate custom logging functionality into your own exception handler to use instead of the Logging Application Block.
- The preceding code example uses a single generic handler for all managed exceptions (these are exceptions derived from the System.Exception class. Your own application could have other catch statements that call the HandleException method with different policies or that do not use the Exception Handling Application Block. The code in this example uses the policy name "Logging Policy" to emphasize its behavior. Generally, a policy name reflects the application layer or component that uses it, instead of its function. For example, a policy used by the data access layer would be named "Data Access Layer Policy."
- If you use the Unity Integration approach to create instances of objects from the Exception Handling Application Block, you must use the non-static façade named ExceptionManager instead of the ExceptionPolicy class static façade.
Changes to the Policy Injection Application Block
The following changes have been made to this version of the Policy Injection Application Block:
- Fixed : Design time for the policy injector collection now reads the default injector from the configuration file. The node creation classes are updated to set the default injector node property on the injectors collection node.
- Changed : The matching classes implementation has changed. The implementation was moved to Unity. The classes still exist in the Policy Injection Application Block as configuration placeholders to provide backward compatibility.
- Changed : The Policy Injection Application Block can now use a container. The container is configured with the Policy Injection Application Block configuration.
- Changed : The Policy Injection Application Block now has only the default interceptor. Non-default interceptor options have been removed. The <injectors> element has been removed. The default interception mechanism of the Policy Injection Application Block enables you to reuse existing object instances.
- Changed Remoting Interception has been renamed Transparent Proxy Interception.