Appendix A — Enterprise Library Integration

  • Article

 

Patterns and Practices home

WS-I Basic Security Profile 1.0 Reference Implementation: Preview release for the .NET Framework version 2.0

Microsoft Corporation

May 2006

Summary: Appendix A describes how the Microsoft patterns & practices Enterprise Library was used to provide functionality within the application.

Contents

Application Blocks
Solution Structure and Application Block Projects
Configuration Console
Sample Application Configuration Information
Exception Handling Application Block
Logging Application Block
Data Access Application Block

The Sample Application uses the Enterprise Library application blocks. Application blocks are reusable software components designed to assist developers with common enterprise development challenges. The Enterprise Library packages together the most widely used application blocks into a single integrated download.

Application Blocks

The Enterprise Library is designed so that its application blocks can function independently of one another. You need to add only the application blocks that your application will use; you do not need to add the entire library. The Sample Application uses the following application blocks from Enterprise Library:

  • Data Access Application Block. This application block simplifies development tasks that require implementing common data access functionality. The Sample Application uses the Data Access Application Block to read and write information to a SQL database.
  • Exception Handling Application Block. This application block allows developers and policy makers to create a consistent strategy for processing exceptions that occur throughout the architectural layers of enterprise applications. The Sample Application uses the Exception Handling Application Block to respond to exceptions in a consistent fashion.
  • Logging and Instrumentation Application Block. This application block allows developers to incorporate standard logging functionality in their applications. The Sample Application does not directly use the Logging Application Block. This application block is used by the Logging Handler supplied by the Exception Handling Application Block when logging exception information.

Solution Structure and Application Block Projects

The Enterprise Library includes the source code for the application blocks. This means you can modify the application blocks to merge into your existing library or you can use parts of the Enterprise Library source code in other application blocks or applications that you build. The Sample Application solution uses unmodified application blocks.

Installing the Sample Application places the source code for the application blocks into the installation directory. The Visual Studio solution file for the Sample Application contains the projects and source code for the application blocks. Each of the Sample Application projects that depend on an application block contains a project reference to that application block.

Each application block also contains a project reference to a common class library (named Common). The Common project contains functionally that is shared by multiple application blocks, such as instrumentation support.

Configuration Console

The Enterprise Library also includes a graphical configuration tool named the Enterprise Library Configuration Console. The Configuration Console provides a way to change and validate application block settings without manually editing the XML configuration files where they are stored. The Configuration Console is included in the Enterprise Library download.

Note: Although the Enterprise Library code used by the Sample Application is included with the application, you must download Enterprise Library separately to use the configuration console. Enterprise Library is available for download at https://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnpag2/html/EntLib2.asp.

After you download and install Enterprise Library, you must copy the file Microsoft.Practices.WSI.SCM.BSP10.CustomPolicyAssertions.dll to the Enterprise Library bin directory (or bin\debug directory if Enterprise Library is in debug mode). At this point you can launch the Configuration Console. To configure application block usage for the Sample Application, open the Web.config file for the Web client or Web service that you want to modify. To open the Web.config file, click the Open Existing Application button on the toolbar. In the Open dialog box, navigate to the folder that contains the Web.config file, click the Web.config file, and then click Open.

Sample Application Configuration Information

The Sample Application requires you to select the specific Web services to be used for the retailer, warehouses (A, B, and C), manufacturers (A, B, and C) and logging facility entities. For each entity, you can choose the specific Web service, or you can choose a predefined set of Web services for all entities.

The configuration information for each Web service is referred to as an endpoint. Each endpoint contains the following configuration information:

  • Role. This describes the specific entity type. It can be any of the following values: LoggingFacility, Retailer, WarehouseA, WarehouseB, WarehouseC, ManufacturerA, ManufacturerB, or ManufacturerC.
  • Description. This is a text description of the Web service. For example, "Retailer on localhost" is the description of the retailer Web service located on the local computer.
  • Url. This is the URL of the Web service.

The following code shows the configuration information for an endpoint as it appears in the XML file.

<Endpoint role="LoggingFacility" 
description="LoggingFacility on localhost"   url="https://localhost/WsiScmSampleApplication/LoggingFacility/LoggingFacility.asmx" />

A collection of endpoints is called an endpoint set. The configuration for the Sample Application allows endpoint sets to be identified by name. The following code shows the configuration information for the endpoint set named "Local" as it appears in the XML file.

<EndpointSet name="Local">
<Endpoint … />
<Endpoint … />
        …<Endpoint … />
</EndpointSet>

Web Client

The Web client allows you to select one of the following preconfigured endpoint sets:

  • Local endpoints. This uses services from the local computer.
  • Microsoft endpoints. This uses services available on a public Microsoft server.
  • Preconfigured mix of endpoints. This uses services from various vendors.

The Web client requests configuration information by specifying the name of a configuration section (for example "localEndpointConfiguration"). The SystemConfigurationSource class is then used to read data from Web.config files.

When the user clicks the Run Demo button with one of the preconfigured options selected, the Web client calls SystemConfiguratonSource to read the endpoint set information for that option. An object of type EndpointConfiguration is then returned to the Web client.

The class EndpointConfiguration is an XML serializable class that represents the configuration settings in object form. In this way, the developer of the Web client does not need to know the form or location of the configuration data. The Web client code contains only references to the objects that hold the configuration data returned by SystemConfigurationSource.

Configuration Service

The Configuration Service provides a method to allow clients to retrieve the endpoint configuration data for the available Web services. The Configuration Service can return endpoint configuration data contained in a local XML file. It can also query UDDI to retrieve endpoint configuration settings. The use of a local XML file and UDDI is determined through the application settings in the Web.config file of the Configuration Service.

<appSettings>
    <add key="UDDIUrl" value="https://uddi.microsoft.com/inquire"/>
    <add key="UseLocalXML" value="true"/>
    <add key="UseUDDI" value="false"/>
</appSettings>

The Configuration Service uses Enterprise Library to read configuration settings from the local XML file.

The Configuration Service calls SystemConfigurationSource, specifying the name of the configuration section endpointConfiguration. Enterprise Library reads the Web.config file to determine the storage location that contains the settings for that configuration section. The Configuration Service is configured to use XML files, and the settings for configuration section endpointConfiguration are stored in the file endpointConfiguration.config.

Exception Handling Application Block

The Exception Handling Block allows you to define policies that govern how exceptions are handled. By specifying the same policy name, exceptions processed by the Exception Handling Application Block are processed in a consistent manner. Because the actions of a policy are controlled through configuration settings, the application behavior in response to an exception can be changed without required application source code changes.

Web Client

The Web client Web pages use try/catch constructs around their operations. In the catch clause, control is passed to the method PublishError of the class UIExceptionHandler. This method calls the Exception Handling Application Block specifying that the policy named Log Only Policy to be used.

The Log Only Policy configuration settings dictate that all exceptions are delivered to a single exception handler, a Logging Handler. That handler sends the exception information to the Logging Application Block. The configuration settings for the handler determine the format of the information and additional attributes used by the Logging Application Block. It also contains the following additional information, which is used by the Logging Application Block to determine if, and where, the exception information will be logged:

  • Category: General
  • Priority: 0
  • Severity: Error

Figure A.1 illustrates the Web client usage of the Exception Handling Application Block.

Figure A.1: How the Web client uses the Exception Handling Application Block

Retailer, Warehouse, and Manufacturer Data Access Component Layers

The Web services available for the retailer, warehouses, and manufactures each contain a data access layer component. The Exception Handling Application Block is used to process exceptions occurring during data access.

The configuration for Data Policy is identical in each of the Web services. According to this configuration, the following will occur when the policy is invoked for exceptions of type SqlException:

  1. A logging handler sends the original exception information to the Logging Application Block. The logged information contains a unique identifier ("handling instance identifier") for the execution of the policy.
  2. The exception is replaced with a new exception of type System.ApplicationException. The new exception message contains the handling instance identifier, providing a means to correlate the new exception with the original exception.

Manufacturer Service

The Manufacturer Service uses the Exception Handling Block to process exceptions that occur during processing. The exceptions are processed according to the policy Log Only Policy; this policy is configured with a single logging handler.

Custom Policy Assertion

The custom policy assertion FaultLoggingAssertion processes exceptions using the policy Fault Logging Policy. This policy is configured with a single logging handler.

SOAP Server Exceptions

The Sample Application Web services generate SOAP exceptions for the exceptions that occur during processing. The application uses the class SoapUtility to create SOAP server exceptions. This class calls the Exception Handling Application Block to process the original exception according to the policy Log Only Policy.

Logging Application Block

The Logging Application Block is responsible for logging messages. It can also filter out log messages and prevent them from being logged. Log messages are filtered by their log categories and their priorities. The Logging Application Block allows you to define your own filters, but it also provides default filters that you can configure to filter out all messages for specified categories or log only messages for specified categories. It allows you to set minimum and maximum priorities for log messages.

The Logging Application Block always processes events synchronously, but the application block can also dump an event to a queue and another instance of the application block can asynchronously receive the messages and process them again, effectively providing asynchronous logging.

Enabling Logging and Tracing

The Sample Application uses a SOAP extension to intercept and log all SOAP messages to a SQL database. The Utilities project in the sample solution uses the Data Access Application Block to read and write the SOAP message data. This project specifies the database instance named TraceLog when creating the Data Access Application Block database object. The name determines the connection string and database system object information that is used when connecting to the underlying database system.

If you are going to use the logging and tracing functionality of the Logging Application Block, you need to ensure that they are enabled. Figure A.2 shows logging and tracing enabled for the Retailer Service.

Figure A.2: Configuring logging and tracing for a Web service

Web Client and Services

The Logging Application Block is not used directly by the Sample Application. Instead, the Sample Application uses the Exception Handling Application Block logging handler, which delivers exception information to the Logging Application Block for processing.

The default Web client and Web service configurations for the Logging Application Block does not filter out any log messages. This means that all exception messages delivered from the Exception Handling Application Block will be logged.

The category of the log message determines where the log message will be delivered for the actual logging operation. The categories General and Data Access Events both specify that log messages are delivered to the event log. This means that all exception messages delivered to the Logging Application Block will appear in the event log.

Data Access Application Block

The Data Access Application Block simplifies development tasks that implement common data access functionality. Applications can use the application block in a variety of situations, such as reading data for display, passing data through application layers, and submitting changed data back to the database system. The application block includes support for both stored procedures and in-line SQL, and common housekeeping tasks, such as managing connections and creating and caching parameters, are encapsulated in the application block's methods. In other words, the Data Access Application Block provides access to the most often used features of ADO.NET while hiding its complexity.

Web Client

The Web client allows users to view the trace information stored in the SQL database. This means that the Web client configuration must include the configuration information for the TraceLog database instance. The Web client configuration information specifies that the TraceLog database instance refers to the SQL database named TraceLog on the local system.

Retailer, Warehouse, and Manufacturer Services

The Retailer, Warehouse, and Manufacturer services each contain a data access layer component. These components wrap the calls to the database, shielding the business components from database interaction. These data access components use the Data Access Application Block to read and write SQL information. The Retailer, Warehouse, and Manufacturer services are configured to use different SQL databases. The databases are defined by the Data Access Application Block configuration settings for each service.

To allow the SOAP extension to write the trace information to a common database target, each of them also includes the identical configuration information for the TraceLog database instance.

Start | Previous | Next

Patterns and Practices home