Multiple Formatter Support for the Logging Application Block

Multiple Formatter Support for the Logging Application Block Scott Densmore, Naveen Yajaman, Paul Slater, and Andrew Mason

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. 2004 Microsoft Corporation. All rights reserved. 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. The names of actual companies and products mentioned herein may be the trademarks of their respective owners.

Contents Multiple Formatter Support for the Logging Application Block 1 Who Should Read This Guide.... 1 Prerequisites... 2 Design of the Multiple Formatter Support for the Logging Application Block... 2 Encryption Formatter Support... 3 Development Using the Logging Application Block with Multiple Formatter Support.... 4 Configuration File Settings for the EncryptionEventFormatter... 5 MultipleFormatters Sample... 5 Deploying Applications that Use Multiple Formatter Support for the Logging Application Block... 6 Summary... 6 Additional Resources 11

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 This guide is targeted at software developers and architects who need to make use of the multiple formatter features of the Logging Application Block in their applications. These applications can range from simple single-server or client applications to distributed applications.

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 /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 IEventFormatter2 Format Void Stream eventinformationtoformat, Stream serializationstream

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 capability to log audit events or application events. The EncryptionEventFormatter uses cryptographic algorithms (SHA1, 3DES, or HMACSHA1 [the default if is the algorithm is not specified in the application configuration file]) to encrypt events. The EncryptionEventFormatter accepts the XML representation of the event as input. The eventproperty.xsd file found in <installation location>\logging\xml\schema (included with the Logging Application Block) gives the schema for the XML representation for serializing the event.

4 Multiple Formatter Support for the Logging Application Block 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 \MultipleFormattersSample.

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> \Logging\Samples\cs, shows how you can use multiple formatters, including the EncryptionEventFormatter, with little or no change to the code. It is similar to the formatting sample included in the Logging Application Block, but uses the encryption event formatter to encrypt audit events.

6 Multiple Formatter Support for the Logging Application Block 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 increases your flexibility in formatting events. With minimal or no change to existing applications that use the block, you should be able to introduce chains of formatters that work together to transform your events. This guide examined the additional capabilities provided by the multiple formatter support for the Logging Application Block and showed how you could use these features in your own environment.

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 subsystems. 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. Relevant They address real-world problems based on customer scenarios. To learn more about patterns & practices visit: http://msdn.microsoft.com/practices To purchase patterns & practices guides visit: http://shop.microsoft.com/practices

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 advice. To learn more about patterns & practices visit: http://msdn.microsoft.com/practices To purchase patterns & practices guides visit: http://shop.microsoft.com/practices

patterns & practices: Current Titles October 2003 Title Link to Online Version Book Patterns Enterprise Solution Patterns using Microsoft.NET Microsoft Data Patterns Reference Architectures Application Architecture for.net: Designing Applications and Services Enterprise Notification Reference Architecture for Exchange 2000 Server Improving Web Application Security: Threats and Countermeasures Microsoft Accelerator for Six Sigma Microsoft Active Directory Branch Office Guide: Volume 1: Planning Microsoft Active Directory Branch Office Series Volume 2: Deployment and Operations Microsoft Content Integration Pack for Content Management Server 2001 and SharePoint Portal Server 2001 Microsoft Exchange 2000 Server Hosting Series Volume 1: Planning Microsoft Exchange 2000 Server Hosting Series Volume 2: Deployment http://msdn.microsoft.com/practices/type/patterns /Enterprise/default.asp http://msdn.microsoft.com/practices/type/patterns /Data/default.asp /library/en-us/dnbda/html/distapp.asp /library/en-us/dnentdevgen/html/enraelp.asp /library/en-us/dnnetsec/html/threatcounter.asp /default.asp?url=/technet/itsolutions/mso/sixsigma /default.asp /default.asp?url=/technet/prodtechnol/ad /windows2000/deploy/adguide/default.asp /default.asp?url=/technet/prodtechnol/ad /windows2000/deploy/adguide/default.asp /library/en-us/dncip/html/cip.asp Online Version not available Online Version not available To learn more about patterns & practices visit: http://msdn.microsoft.com/practices To purchase patterns & practices guides visit: http://shop.microsoft.com/practices

Title Link to Online Version Book Microsoft Exchange 2000 Server Upgrade Series Volume 1: Planning Microsoft Exchange 2000 Server Upgrade Series Volume 2: Deployment Microsoft Solution for Intranets Microsoft Solution for Securing Wireless LANs Microsoft Systems Architecture Enterprise Data Center Microsoft Systems Architecture Internet Data Center The Enterprise Project Management Solution UNIX Application Migration Guide Reference Building Blocks and IT Services.NET Data Access Architecture Guide Application Updater Application Block Asynchronous Invocation Application Block Authentication in ASP.NET:.NET Security Guidance Building Interoperable Web Services: WS-I Basic Profile 1.0 Building Secure ASP.NET Applications: Authentication, Authorization, and Secure Communication /default.asp?url=/technet/itsolutions/guide /default.asp /default.asp?url=/technet/itsolutions/guide /default.asp /default.asp?url=/technet/itsolutions/mso /msi/default.asp http://www.microsoft.com/downloads /details.aspx?familyid=cdb639b3-010b-47e7-b23 4-A27CDA291DAD&displaylang=en /default.asp?url=/technet/itsolutions/edc /Default.asp / default.asp?url=/technet/itsolutions/idc/default.asp /default.asp?url=/technet/itsolutions/mso/epm /default.asp /library/en-us/dnucmg/html/ucmglp.asp /library/en-us/dnbda/html/daag.asp /library/en-us/dnbda/html/updater.asp /library/en-us/dnpag/html/paiblock.asp /library/en-us/dnbda/html/authaspdotnet.asp /library/en-us/dnsvcinter/html/wsi-bp_msdn_ landingpage.asp /library/en-us/dnnetsec/html/secnetlpmsdn.asp To learn more about patterns & practices visit: http://msdn.microsoft.com/practices To purchase patterns & practices guides visit: http://shop.microsoft.com/practices

Title Link to Online Version Book Caching Application Block Caching Architecture Guide for.net Framework Applications Configuration Management Application Block Data Access Application Block for.net Designing Application-Managed Authorization Designing Data Tier Components and Passing Data Through Tiers Exception Management Application Block for.net Exception Management Architecture Guide Microsoft.NET/COM Migration and Interoperability /library/en-us/dnpag/html/cachingblock.asp /library/en-us/dnbda/html/cachingarch.asp?frame= true /library/en-us/dnbda/html/cmab.asp /library/en-us/dnbda/html/daab-rm.asp http://msdn.microsoft.com/library/?url=/library /en-us/dnbda/html/damaz.asp /library/en-us/dnbda/html/boagag.asp /library/en-us/dnbda/html/emab-rm.asp /library/en-us/dnbda/html/exceptdotnet.asp /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 Application Design New Application Installation using Systems Management Server Patch Management using Microsoft Systems Management Server - Operations Guide Patch Management Using Microsoft Software Update Services - Operations Guide Service Aggregation Application Block Service Monitoring and Control using Microsoft Operations Manager /library/en-us/dnbda/html/monitordotnet.asp http://www.microsoft.com/business/reducecosts /efficiency/manageability/application.mspx / default.asp?url=/technet/itsolutions/msm/swdist/ pmsms/pmsmsog.asp / default.asp?url=/technet/itsolutions/msm/swdist/ pmsus/pmsusog.asp /library/en-us/dnpag/html/serviceagg.asp http://www.microsoft.com/business/reducecosts /efficiency/manageability/monitoring.mspx To learn more about patterns & practices visit: http://msdn.microsoft.com/practices To purchase patterns & practices guides visit: http://shop.microsoft.com/practices

Title Link to Online Version Book User Interface Process Application Block Web Service Façade for Legacy Applications Lifecycle Practices Backup and Restore for Internet Data Center Deploying.NET Applications: Lifecycle Guide Microsoft Exchange 2000 Server Operations Guide Microsoft SQL Server 2000 High Availability Series: Volume 1: Planning Microsoft SQL Server 2000 High Availability Series: Volume 2: Deployment Microsoft SQL Server 2000 Operations Guide Operating.NET-Based Applications Production Debugging for.net-connected Applications Security Operations for Microsoft Windows 2000 Server Security Operations Guide for Exchange 2000 Server Team Development with Visual Studio.NET and Visual SourceSafe /library/en-us/dnbda/html/uip.asp /library/en-us/dnpag/html/wsfacadelegacyapp.asp /default.asp?url=/technet/ittasks/maintain/backuprest/default.asp /library/en-us/dnbda/html/dalgroadmap.asp /default. asp?url=/technet/prodtechnol/exchange/exchange 2000/maintain/operate/opsguide/default.asp /default.asp?url=/technet/prodtechnol/sql/deploy /confeat/sqlha/sqlhalp.asp /default.asp?url=/technet/prodtechnol/sql/deploy /confeat/sqlha/sqlhalp.asp /default.asp?url=/technet/prodtechnol/sql/maintain /operate/opsguide/default.asp /default.asp?url=/technet/itsolutions/net/maintain /opnetapp/default.asp /library/en-us/dnbda/html/dbgrm.asp /default.asp?url=/technet/security/prodtech /win2000/secwin2k/default.asp /default.asp?url=/technet/security/prodtech /mailexch/opsguide/default.asp /library/en-us/dnbda/html/tdlg_rm.asp This title is available as a Book To learn more about patterns & practices visit: http://msdn.microsoft.com/practices To purchase patterns & practices guides visit: http://shop.microsoft.com/practices