Multiple Formatter Support for the Logging Application Block

(1)

Multiple Formatter Support for

the Logging Application Block

(2)

Information in this document, including URL and other Internet Web site references, is subject to change without notice. Unless otherwise noted, the example companies, organizations, products, domain names, e-mail addresses, logos, people, places, and events depicted herein are fictitious, and no association with any real company, organization, product, domain name, e-mail address, logo, person, place, or event is intended or should be inferred. Complying with all applicable copyright laws is the responsibility of the user. Without limiting the rights under copyright, no part of this document may be reproduced, stored in or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or otherwise), or for any purpose, without the express written permission of Microsoft Corporation.

Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. Except as expressly provided in any written license agreement from Microsoft, the furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property.

Microsoft, MS-DOS, Windows, Windows NT, Windows Server, MSDN, and Visual Basic are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.

(3)

Multiple Formatter Support for the

Logging Application Block

If you are involved in designing and developing Microsoft®

.NET Framework applications, you may be using the Logging Application Block to provide you with effective logging in your applications. The block is a reusable code component that uses the Microsoft Enterprise Instrumentation Framework (EIF) and the Microsoft .NET Framework to help you design instrumented applications.

The Logging Application Block provides extensions to the EIF architecture that help to address common usage scenarios for logging. These scenarios include:

● Formatting event information ● Configuring log levels

● Enhanced information in the published events ● Asynchronous logging

● Reliable logging ● Centralized logging

● Request tracing for Web services ● Metering for Web services

● Using the EIF publisher for the Exception Management Application Block (EMAB) The data transformation functionality in the Logging Application Block is responsible for formatting events before they are stored in the event sink and is designed to support any formatter. However, the original design of the Logging Application Block supported the use of only a single formatter per event or sink. To work around this restriction, the new version of the block now supports multiple formatters. An additional formatter is also supplied: the EncryptionEventFormatter, which supports encryption of events.

This guide discusses the design changes to the block to support multiple formatters, shows how to use the block in your applications to support multiple formatters, and examines how to deploy applications that include the new version of the block.

Who Should Read This Guide

(5)

2 Multiple Formatter Support for the Logging Application Block

Prerequisites

Prior to reading this guide, you should read the Logging Application Block guide in its entirety at http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnpag/html /logging.asp. The Logging Application Block guide describes the design and features of the Logging Application Block and demonstrates how you can use the block to produce instrumented applications. It also gives an overview of EIF and Web Services Enhancements (WSE).

To benefit fully from this guide, you should have a full understanding of the Logging Application Block, the .NET Framework (including .NET Framework security concepts), and how to use the framework to develop and deploy Web services. You should also be familiar with the following technologies:

the C# language, Microsoft Visual Basic® .NET, XML, Web Services Enhancements (WSE), Windows Management Instrumentation (WMI), Microsoft Message Queuing (MSMQ), and Microsoft SQL Server™.

Design of the Multiple Formatter Support for the Logging

Application Block

The original design of the Logging Application Block supported the use of a single formatter per event or sink, which implemented the IEventFormatter interface. This design has now been enhanced to support multiple formatters, where the formatters are chained together and executed in order.

If you are going to make use of the multiple formatter functionality, you will need to create formatters that implement a new interface supplied with the block, called IEventFormatter2. The IEventFormatter2 interface is inherited from the IEventFormatter interface. It supports the same Format method supported by IEventFormatter. However, whereas the method supported by IEventFormatter requires the input parameter to be of the type System.Xml.XPath.XPathDocument, the method supported by IEventFormatter2 accepts data formatted as a stream. Table 1 shows the two methods.

Table 1: Format Methods of the IEventFormatter and IEventFormatter2 Interfaces

Interface Method Type Parameters

IEventFormatter Format Void XPathDocument eventInformationToFormat, Stream serializationStream

(6)

Multiple Formatter Support for the Logging Application Block 3

This design allows you to chain together calls to a formatter. Figure 1 shows an event sink making consecutive calls to different formatters.

Figure 1

An event sink making consecutive calls to multiple formatters

Because multiple formatters are supported in this way, any formatter downstream in the chain must understand the output of the preceding formatter. Any new formatter should implement the IEventFormatter2 interface.

Encryption Formatter Support

The Logging Application Block now includes a new formatter that supports encryption, called EncryptionEventFormatter. You can use the encryption

(7)

Development Using the Logging Application Block with

Multiple Formatter Support

To support multiple formatters in the Logging Application Block, you will need to make a number of modifications to the application configuration file, the EIF configuration file, and the client application itself.

To enable event transformation for a particular event sink, you need to set the enableFormatting parameter value in the EIF configuration file to true. By default, the Logging Application Block sets enableFormatting to false.

The formatters you are using also need to be specified in order. You can specify the chain of formatters on a per-sink basis in the EIF configuration file by modifying the formatterName parameter on the type property for the event sink. You can also specify the chain on a per-event basis, either by setting the formatterName property directly in the application code to contain the formatter chain before raising the event, or by specifying the value in the application configuration file and writing application code to get the value when required. The formatterName property contains a string value, and contains each of the formatters, in order, separated by a semicolon ( ; ). This means that the semicolon is not a valid character in the formatter names themselves.

You also need to specify each formatter to use in the <eventFormatterSettings> section of the application configuration file or Web configuration file. Each formatter used is defined by the formatterInfo element. The element includes the formatter name, the fully qualified type name, and any special data that will be passed on to the actual provider type. In many cases, the application code does not need to be changed at all to support multiple formatters. You will need to make modifications if the formatter name is specified directly in the code, which may be the case if you are specifying which formatter to use on a per-event basis.

To view an example EIF configuration file and application configuration file with the settings mentioned in the previous discussion, see the

EnterpriseInstrumentation.config and App.config files in the MultipleFormatters sample, located in the folder <installation location>\Logging\Samples\cs

(8)

Multiple Formatter Support for the Logging Application Block 5

Configuration File Settings for the EncryptionEventFormatter

If you want to use the EncryptionEventFormatter supplied with the Logging Application Block, you need to make changes to the application configuration file to support the use of the formatter. As well as specifying the formatter in the <eventFormatterSettings> section, you also need to create a section called <cryptographicSettings>. The section defines all of the cryptographic providers available. Each provider is defined by a cryptographicInfo element, which contains a name corresponding to the cryptoProvider attribute specified in the <eventFormatterSettings> section. The cryptographicInfo element also specifies the fully qualified type, and any defined data that will be passed to the provider. If you are using the Data Protection API (DPAPI) provider, you must also specify a

validation key and validation type.

The following code snippet shows configuration file settings for the EncryptionEventFormatter: <configSections> <section name="eventFormatterSettings" type="Microsoft.ApplicationBlocks.Logging.EventSinks.FormatterConfigHandler, Microsoft.ApplicationBlocks.Logging.EventSinks" /> <section name="crytpographicSettings" type="Microsoft.ApplicationBlocks.Common.Crypto.CryptographicConfigurationHandler, Microsoft.ApplicationBlocks.Common" /> </configSections> <eventFormatterSettings> <formatterInfo name="cryptoFormatter" type="Microsoft.ApplicationBlocks.Logging.EventSinks.EncryptionEventFormatter, Microsoft.ApplicationBlocks.Logging.EventSinks" cryptoProvider="default"/> </eventFormatterSettings> <crytpographicSettings> <cryptographicInfo name="default" type="Microsoft.ApplicationBlocks.Common.Crypto.DPAPIProvider, Microsoft.ApplicationBlocks.Common" validationKey="Oci44OQ9C3xAdQ3/BMHpksPfzeTezLkXen/ahQ8T7nVk/KMgAFnssQJr00KUNhRso+M pLVwAinGep6i14X9M+A==" validation="SHA1"/> </crytpographicSettings>

MultipleFormatters Sample

The MultipleFormatters sample, located in the folder <installation location>

(9)

The sample behaves much as the formatting sample does, except that it uses multiple formatters. In fact, in the application itself only one line of code is modified: the name of the formatter used for per-event formatting.

Note: When using the Visual Basic .NET sample, located in the folder <installation location>\Logging \Samples\vb\MultipleFormattersSample, you must run PostBuildEvent.bat before running the sample code.

Deploying Applications that Use Multiple Formatter Support for

the Logging Application Block

There are no new deployment considerations for applications that use the multiple formatter support included with the Logging Application Block. However, if you have existing applications that you want to modify to use the multiple formatter functionality of the block, you will need to redeploy the Logging Application Block itself, the EIF configuration file, and the application configuration file. You may also need to redeploy the application itself if the code directly specifies the formatters to use.

The Logging Application Block now includes a new assembly, called Common. This assembly stores code common to different application blocks. If you want to deploy this assembly in the global assembly cache, you need to use the fully qualified type name.

Note: The Common project uses a different key than the Logging Application Block, so the public key token value for the fully qualified type name for types in the Common assembly will be different.

Summary

The ability to use multiple formatters with the Logging Application Block

(10)

About Microsoft patterns & practices

Microsoft patterns & practices guides contain specific recommendations illustrating how to design, build, deploy, and operate architecturally sound solutions to challenging business and technical scenarios. They offer deep technical guidance based on real-world experience that goes far beyond white papers to help enterprise IT professionals, information workers, and developers quickly deliver sound solutions.

IT Professionals, information workers, and developers can choose from four types of patterns &

practices:

● Patterns—Patterns are a consistent way of documenting solutions to commonly occurring

problems. Patterns are available that address specific architecture, design, and implementation problems. Each pattern also has an associated GotDotNet Community.

● Reference Architectures—Reference Architectures are IT system-level architectures that

address the business requirements, LifeCycle requirements, and technical constraints for commonly occurring scenarios. Reference Architectures focus on planning the architecture of IT systems.

● Reference Building Blocks and IT Services—References Building Blocks and IT Services are

re-usable sub-system designs that address common technical challenges across a wide range of scenarios. Many include tested reference implementations to accelerate development. Reference Building Blocks and IT Services focus on the design and implementation of sub-systems.

● Lifecycle Practices—Lifecycle Practices provide guidance for tasks outside the scope of

architecture and design such as deployment and operations in a production environment.

Patterns & practices guides are reviewed and approved by Microsoft engineering teams, consultants,

Product Support Services, and by partners and customers. Patterns & practices guides are:

● Proven—They are based on field experience.

● Authoritative—They offer the best advice available.

● Accurate—They are technically validated and tested.

● Actionable—They provide the steps to success.

(11)

Patterns & practices guides are designed to help IT professionals, information workers, and

developers:

Reduce project cost

● Exploit the Microsoft engineering efforts to save time and money on your projects.

● Follow the Microsoft recommendations to lower your project risk and achieve predictable

outcomes.

Increase confidence in solutions

● Build your solutions on proven Microsoft recommendations so you can have total confidence in

your results.

● Rely on thoroughly tested and supported guidance, but production quality recommendations and

code, not just samples. Deliver strategic IT advantage

● Solve your problems today and take advantage of future Microsoft technologies with practical

(12)

patterns & practices: Current Titles October 2003

Title Link to Online Version Book

Patterns

Enterprise Solution Patterns http://msdn.microsoft.com/practices/type/Patterns

using Microsoft .NET /Enterprise/default.asp

Microsoft Data Patterns http://msdn.microsoft.com/practices/type/Patterns

/Data/default.asp

Reference Architectures

Application Architecture for http://msdn.microsoft.com/library/default.asp?url=

.NET: Designing Applications /library/en-us/dnbda/html/distapp.asp

and Services

Enterprise Notification http://msdn.microsoft.com/library/default.asp?url=

Reference Architecture for /library/en-us/dnentdevgen/html/enraelp.asp

Exchange 2000 Server

Improving Web Application http://msdn.microsoft.com/library/default.asp?url=

Security: Threats and /library/en-us/dnnetsec/html/ThreatCounter.asp

Countermeasures

Microsoft Accelerator http://www.microsoft.com/technet/treeview

for Six Sigma /default.asp?url=/technet/itsolutions/mso/sixsigma

/default.asp

Microsoft Active Directory http://www.microsoft.com/technet/treeview

Branch Office Guide: /default.asp?url=/technet/prodtechnol/ad

Volume 1: Planning /windows2000/deploy/adguide/default.asp

Microsoft Active Directory http://www.microsoft.com/technet/treeview

Branch Office Series /default.asp?url=/technet/prodtechnol/ad

Volume 2: Deployment and /windows2000/deploy/adguide/default.asp

Operations

Microsoft Content Integration http://msdn.microsoft.com/library/default.asp?url=

Pack for Content Management /library/en-us/dncip/html/cip.asp

Server 2001 and SharePoint Portal Server 2001

Microsoft Exchange 2000 Online Version not available

Server Hosting Series Volume 1: Planning

Microsoft Exchange 2000 Online Version not available

(13)

Microsoft Exchange 2000 http://www.microsoft.com/technet/treeview

Server Upgrade Series /default.asp?url=/technet/itsolutions/guide

Volume 1: Planning /default.asp

Microsoft Exchange 2000 http://www.microsoft.com/technet/treeview

Server Upgrade Series /default.asp?url=/technet/itsolutions/guide

Volume 2: Deployment /default.asp

Microsoft Solution http://www.microsoft.com/technet/treeview

for Intranets /default.asp?url=/technet/itsolutions/mso

/msi/Default.asp

Microsoft Solution for http://www.microsoft.com/downloads

Securing Wireless LANs /details.aspx?FamilyId=CDB639B3-010B-47E7-B23

4-A27CDA291DAD&displaylang=en

Microsoft Systems http://www.microsoft.com/technet/treeview

Architecture— /default.asp?url=/technet/itsolutions/edc

Enterprise Data Center /Default.asp

Microsoft Systems http://www.microsoft.com/technet/treeview/

Architecture— default.asp?url=/technet/itsolutions/idc/default.asp

Internet Data Center

The Enterprise Project http://www.microsoft.com/technet/treeview

Management Solution /default.asp?url=/technet/itsolutions/mso/epm

/default.asp

UNIX Application http://msdn.microsoft.com/library/default.asp?url=

Migration Guide /library/en-us/dnucmg/html/ucmglp.asp

Reference Building Blocks and IT Services

.NET Data Access http://msdn.microsoft.com/library/default.asp?url=

Architecture Guide /library/en-us/dnbda/html/daag.asp

Application Updater http://msdn.microsoft.com/library/default.asp?url=

Application Block /library/en-us/dnbda/html/updater.asp

Asynchronous Invocation http://msdn.microsoft.com/library/default.asp?url=

Application Block /library/en-us/dnpag/html/paiblock.asp

Authentication in ASP.NET: http://msdn.microsoft.com/library/default.asp?url=

.NET Security Guidance /library/en-us/dnbda/html/authaspdotnet.asp

Building Interoperable Web http://msdn.microsoft.com/library/default.asp?url=

(14)

Caching Application Block http://msdn.microsoft.com/library/default.asp?url=

/library/en-us/dnpag/html/Cachingblock.asp

Caching Architecture Guide for http://msdn.microsoft.com/library/default.asp?url=

.Net Framework Applications /library/en-us/dnbda/html/CachingArch.asp?frame=

true

Configuration Management http://msdn.microsoft.com/library/default.asp?url=

Application Block /library/en-us/dnbda/html/cmab.asp

Data Access Application Block http://msdn.microsoft.com/library/default.asp?url=

for .NET /library/en-us/dnbda/html/daab-rm.asp

Designing Application-Managed http://msdn.microsoft.com/library/?url=/library

Authorization /en-us/dnbda/html/damaz.asp

Designing Data Tier Components http://msdn.microsoft.com/library/default.asp?url=

and Passing Data Through Tiers /library/en-us/dnbda/html/BOAGag.asp

Exception Management http://msdn.microsoft.com/library/default.asp?url=

Application Block for .NET /library/en-us/dnbda/html/emab-rm.asp

Exception Management http://msdn.microsoft.com/library/default.asp?url=

Architecture Guide /library/en-us/dnbda/html/exceptdotnet.asp

Microsoft .NET/COM Migration http://msdn.microsoft.com/library/default.asp?url=

and Interoperability /library/en-us/dnbda/html/cominterop.asp

Microsoft Windows Server http://www.microsoft.com/downloads/

2003 Security Guide

details.aspx?FamilyId=8A2643C1-0685-4D89-B655-521EA6C7B4DB&displaylang=en

Monitoring in .NET Distributed http://msdn.microsoft.com/library/default.asp?url=

Application Design /library/en-us/dnbda/html/monitordotnet.asp

New Application Installation http://www.microsoft.com/business/reducecosts

using Systems Management /efficiency/manageability/application.mspx

Server

Patch Management using http://www.microsoft.com/technet/treeview/

Microsoft Systems Management default.asp?url=/technet/itsolutions/msm/swdist/

Server - Operations Guide pmsms/pmsmsog.asp

Patch Management Using http://www.microsoft.com/technet/treeview/

Microsoft Software Update default.asp?url=/technet/itsolutions/msm/swdist/

Services - Operations Guide pmsus/pmsusog.asp

Service Aggregation Application http://msdn.microsoft.com/library/default.asp?url=

(15)

User Interface Process http://msdn.microsoft.com/library/default.asp?url=

Application Block /library/en-us/dnbda/html/uip.asp

Web Service Façade for http://msdn.microsoft.com/library/default.asp?url=

Legacy Applications /library/en-us/dnpag/html/wsfacadelegacyapp.asp

Lifecycle Practices

Backup and Restore for http://www.microsoft.com/technet/treeview/default.asp

Internet Data Center ?url=/technet/ittasks/maintain/backuprest/Default.asp

Deploying .NET Applications: http://msdn.microsoft.com/library/default.asp?url=

Lifecycle Guide /library/en-us/dnbda/html/DALGRoadmap.asp

Microsoft Exchange 2000 http://www.microsoft.com/technet/treeview/default.

Server Operations Guide asp?url=/technet/prodtechnol/exchange/exchange

2000/maintain/operate/opsguide/default.asp

Microsoft SQL Server 2000 http://www.microsoft.com/technet/treeview

High Availability Series: /default.asp?url=/technet/prodtechnol/sql/deploy

Volume 1: Planning /confeat/sqlha/SQLHALP.asp

High Availability Series: /default.asp?url=/technet/prodtechnol/sql/deploy

Volume 2: Deployment /confeat/sqlha/SQLHALP.asp

Operations Guide /default.asp?url=/technet/prodtechnol/sql/maintain

/operate/opsguide/default.asp

Operating .NET-Based http://www.microsoft.com/technet/treeview

Applications /default.asp?url=/technet/itsolutions/net/maintain

/opnetapp/default.asp

Production Debugging for http://msdn.microsoft.com/library/default.asp?url=

.NET-Connected Applications /library/en-us/dnbda/html/DBGrm.asp

Security Operations for http://www.microsoft.com/technet/treeview

Microsoft Windows 2000 Server /default.asp?url=/technet/security/prodtech

/win2000/secwin2k/default.asp

Security Operations Guide for http://www.microsoft.com/technet/treeview

Exchange 2000 Server /default.asp?url=/technet/security/prodtech

/mailexch/opsguide/default.asp

Team Development with Visual http://msdn.microsoft.com/library/default.asp?url=

Multiple Formatter Support for the Logging Application Block

Multiple Formatter Support for

the Logging Application Block

Contents

Multiple Formatter Support for the Logging Application Block

1

Multiple Formatter Support for the

Logging Application Block

Who Should Read This Guide

Prerequisites

Design of the Multiple Formatter Support for the Logging

Application Block

Encryption Formatter Support

Development Using the Logging Application Block with

Multiple Formatter Support

Configuration File Settings for the EncryptionEventFormatter

MultipleFormatters Sample

Deploying Applications that Use Multiple Formatter Support for

the Logging Application Block

Summary