This post disappeared from a previous blog of mine so I'm reposting it.
---
Earlier this year Microsoft released the Enterprise Library v1.0. The Enterprise Library consists of several Application Blocks that can be used to provide software infrastructure for enterprise application development. According to the Enterprise Library documentation, the “Application blocks are reusable software components designed to assist developers with common enterprise development challenges.” One of these Application Blocks, the Logging and Instrumentation Application Block, is the part of the focus of this article.
The purpose of this article is to explain how to set up the Logging and Instrumentation Application Block for BizTalk Server 2004 and BizTalk Server 2004 applications and to examine a simple sample application show its usage in a BizTalk Server 2004 application. Detailed discussion on when and how to log are not covered in this article.
Why Logging is Important in BizTalk Server 2004 Applications
Although BizTalk Server 2004 supports tracking and the viewing of tracking data in HAT there are very good reasons for using ‘traditional’ logging and methods in BizTalk Server 2004 applications:
· BizTalk Server 2004 tracking has a performance degradation cost associated with it; in some cases the performance degradation cost can be substantial.
· You can gain explicit control as to when logging messages are sent using logging filters.
· You can gain explicit control as to how the logging messages are sent (Event Log, database, file, email, etc.)
· You can categorize logging messages (debug, exception, trace, etc.)
· You gain control of the format of the logging messages.
· You can create your own events/notifications that could be subscribed to with other software components.
· If you do not have access to HAT in your production environment you can still get valuable data ‘sent’ to your development team.
Scott Colestock wrote an article on using log4net in BizTalk Server 2004 here. His article also contains some additional reasons why ‘traditional’ logging is still important in BizTalk Server 2004 applications.
Logging and Instrumentation Application Block Core Concepts
From the Logging and Instrumentation Application Block Documentation:
“The Enterprise Library Logging and Instrumentation Application Block version 1.0, lets developers incorporate standard logging and instrumentation functionality in their applications. Applications can use the Logging and Instrumentation Block to log events to a variety of locations:
· The event log
· E-mail messages
· A database
· A message queue
· A file WMI
The Logging and Instrumentation Application Block helps with application development in a number of ways:
· It helps maintain consistent logging and instrumentation practices, both within an application and across the enterprise. It eases the learning curve for developers by using a consistent architectural model.
· It provides implementations that you can use to solve common application logging and instrumentation problems.
· It is extensible, supporting custom implementations of formatters and event sinks.”
The Logging and Instrumentation Application Block contains several extension points including creating new categories for logging, creating new event sinks, and new context providers.
Prerequisites and Installation
· Obtain the Enterprise Library from http://www.microsoft.com/downloads/details.aspx?FamilyID=0325B97A-9534-4349-8038-D56B38EC394C&displaylang=en
· Install the Enterprise Library, following the instructions included with it; there are patches for the Enterprise Library available at http://www.gotdotnet.com/workspaces/workspace.aspx?id=295a464a-6072-4e25-94e2-91be63527327
· Read the documentation for the Configuration and Logging and Instrumentation Application Blocks
o Go to Start, All Programs, Microsoft patterns and practices, Enterprise Library, Enterprise Library Documentation.
· Other suggested reading topics on the Logging and Instrumentation Application Block:
o http://blog.hishambaz.com/archive/2005/01/29/194.aspx
o http://blog.hishambaz.com/archive/2005/01/30/202.aspx
o http://blog.hishambaz.com/archive/2005/02/05/253.aspx
o http://www.codeproject.com/dotnet/GetLoggingWithEntLib.asp
Setting up the Logging and Instrumentation Application Block for BizTalk Server 2004
These instructions are for setting up the Enterprise Library for use within BizTalk Server 2004 applications, on a machine with Visual Studio.NET 2003 installed.
· So that the Logging and Instrumentation Application Block can be used from BizTalk Server 2004, you must associate the non-.Design projects (projects names ending in .Design) with a .snk so that they can be deployed to the GAC; I signed all non-.Design projects (all project’s that do not have names ending in ‘.Design’) to keep things simple.
o Open the Enterprise Library solution
§ Go to Start, All Programs, Microsoft patterns and practices, Enterprise Library, Application Blocks for .NET, Enterprise Library Solution
o Associate the non-.Design projects with the C:\POC_BTS_LoggingAppBlock\EnterpriseLibrary.snk; if you do not sign it with this .snk, you will need to update the three of the four .config files associated with the sample before it will work correctly. You will need to update the PublicKeyToken references so that their value is set to the public key token associated with your .snk.
o Rebuild the Enterprise Library.
o Move the assemblies to the Enterprise Library’s bin directory.
o If you have already installed the services you need to uninstall the services.
o Now Install Services.
o Install the assemblies into the GAC.
o If you are performing these actions on a workstation with VS.NET installed you can use the shortcuts at Start, All Programs, Microsoft patterns and practices, Enterprise Library to perform the last five steps.
o Note that out-of-the-box, the InstallServices.bat, that is called from the Install Services command, requires Visual Studio.NET 2003 to be installed on the machine that it executes on; in order to Install Services on a server without Visual Studio.NET 2003 reference these posts:
§ http://blogs.msdn.com/scottdensmore/archive/2005/03/17/397950.aspx
§ http://martijnh.blogspot.com/2005/03/microsoft-enterprise-library-custom.html
o Note, you should not use the EnterpriseLibrary.snk for your actual implementations; it is only provided to keep the sample’s setup as simple as possible.
· On Windows 2003, add the BizTalk service accounts, for the host instances that will host orchestrations using the Logging and Instrumentation Application Block, to the local ‘Performance Monitors Users’ group
Setting up BizTalk Server 2004 Application to use the Logging and Instrumentation Application Block
The Enterprise Library requires a ‘root’ configuration file. The ‘root’ configuration file references other files where the Enterprise Library’s configuration data is stored. This means that for ‘normal’ .NET applications the ‘root’ configuration file will either be the app.config or web.config. By default, the BizTalk Server 2004, the ‘root’ .config file is [InstallDrive]\Program Files\Microsoft BizTalk Server 2004\BTSNTSvc.exe.config. There are other options with BizTalk Server 2004; you can set up your own ‘default’ .config file for all AppDomains or you can use BizTalk’s ability to assign assemblies to Application Domains and associate the App Domains with a specific .config file. Both of these options are accomplished my modifying the BTSNTSvc.exe.config file.
BTSNTSvc.exe.config
If you use this file as your ‘root’ .config file all of your BizTalk Server 2004 applications will utilize the same instance of your Logging and Instrumentation Application Block’s configuration. Restated this means all of your BizTalk Server 2004 applications will be subject to a global configuration (to BizTalk) for the Logging and Instrumentation Application Block. This may or may not be appropriate for you situation. The sample application does not use this file for its ‘root’ configuration file.
AppDomain Assignment
Another option in BizTalk Server 2004 is to use its App Domain assignment feature. You can assign BizTalk assemblies to a default application domain or to specific Application Domains using ‘Exact Assignment’ or ‘Pattern Assignment’; this means using the full name of the assembly or regular expressions, respectively. You can create a default specification for App Domains using the DefaultSpec element. You can create custom App Domains, and assembly assignments for them, using the AppDomainSpec element.
App Domain assignment may or may not be appropriate for you situation but it is the mechanism used in the sample for setting a ‘root’ configuration file for the Logging and Instrumentation Application Block.
This feature is ‘documented’ in the SDK at http://www.msdn.microsoft.com/library/en-us/sdk/htm/ebiz_prog_orch_jzex.asp. There is also a blog entry by Todd Uhl explaining this feature.
Note:
· Utility assemblies, call from orchestrations will be loaded into the same App Domain as the orchestration that uses it.
- The account associated with the host instance (that will use the Logging and Instrumentation Application Block) is running under will need to have access to the ‘root’ .config file and the other .config files created by the Enterprise Library Configuration application.
The generic steps to set up the Logging and Instrumentation Application Block in a BizTalk Server 2004 Application when you are using AppDomain assignment are:
· Reference the Microsoft.Practices.EnterpriseLibrary.Logging .dll (assembly) or project.
· Use the Microsoft.Practices.EnterpriseLibrary.Logging.Logger.Write() method to write logging messages in orchestration assembly shapes and utility components.
· Update the BTSNTSvc.config (after backing it up) file so that the orchestration assembly is assigned to an AppDomain:
<AppDomainSpecs>
<AppDomainSpec Name=”POC_BTS_LoggingAppBlock_BizTalk” SecondsIdleBeforeShutdown=”-1” SecondsEmptyBeforeShutdown=”12000”>
<BaseSetup>
<ConfigurationFile>C:\POC_BTS_LoggingAppBlock\POC_BTS_LoggingAppBlock.config</ConfigurationFile>
</BaseSetup>
</AppDomainSpec>
</AppDomainSpecs>
<!—
The PatternAssignmentRules and ExactAssignmentRules control assignment of assemblies to app domains.
When a message arrives, the name of its corresponding orchestration’s assembly is determined. Then, the assembly is assigned an app domain name. The rules guide this assignment. Exact rules are consulted first, in their order of definition, and then the pattern rules. The first match is used.
If no match is found, the assembly will be assigned to an ad-hoc domain. The configuration and number of assemblies per ad-hoc domain is controlled by the AssembliesPerDomain attribute and the DefaultSpec section.
à
<ExactAssignmentRules>
<!—
An exact assembly rule specifies a strong assembly name and an app domain name. If the strong assembly name equals the rule’s assembly name, it is assigned to the corresponding app domain.
à
<ExactAssignmentRule AssemblyName=”POC_BTS_LoggingAppBlock_BizTalk, Version=1.0.0.0, Culture=neutral, PublicKeyToken=b65652986d7b9da4”
AppDomainName=”POC_BTS_LoggingAppBlock_BizTalk” />
</ExactAssignmentRules>
· Store your ‘root’ configuration file, and the other .config files that the Enterprise Library Configuration application creates, in the location specified in the appropriate AppDomainSpecs/AppDomainSpec/BaseSetup/ConfigurationFile.
Sample BizTalk Server 2004 Application using the Logging and Instrumentation Application Block
A sample application utilizing the Logging and Instrumentation Application Block can be downloaded from the GotDotNet User Samples, here. If you have problems downloading the sample from GotDotNet, reference the ‘Feedback’ section of this article for information on contacting me; I will be happy to send it to you.
The sample is a very simple sample application that uses the Logging and Instrumentation Application Block from an expression shape, in an orchestration, and from a utility component called from the same orchestration. An atomic scope is used the orchestration to guarantee that at least one persistence point is reached prior to the last call to Logger.Write(); this gave me an indication as to how the Logging and Instrumentation Application Block would act in a ‘normal’ long-running orchestration scenario where the orchestration was persisted. The sample application uses the App Domain assignment method for associating an orchestration assembly with a ‘root’ configuration file.
This logging configuration has four categories:
· Default – which is the default category with a new Logging and Instrumentation Application Block configuration; it is associated with an Event Log Sink. This category is not used in the sample.
· Trace – another default associated with a Flat File Sink that writes to trace.log. This category is only used if the Logging and Instrumentation Application Block’s tracing is turned on. It is not used in this sample.
· INFO – a custom category for the sample; it is associated with a Flat File Sink named INFO Flat File Sink that writes to C:\POC_BTS_LoggingAppBlock\POC_BTS_LoggingAppBlock_BizTalk\info.log
· DEBUG – another custom category for this sample that is associated with an Event Log Sink
There are four .config files associated with this sample:
· BTSNTSvc.exe.config – contains the App Domain assignment settings for the sample (and other default settings that come with original file installed with BizTalk Server 2004.)
· POC_BTS_LoggingAppBlock_BizTalk.dll.config – contains references to two files used by the Logging and Instrumentation Application Block.
· loggingConfiguration.config – used by the Logging and Instrumentation Application Block.
· loggingDistributorConfiguration.config – used by the Logging and Instrumentation Application Block.
Setting up the Sample Application
After the Logging and Instrumentation Application Block is set up for usage in a BizTalk Server 2004 application additional setup steps must be completed for each BizTalk Server 2004 application that uses it. For the sample application, these steps are:
· Perform all of the steps in the ‘Setting up the Logging and Instrumentation Application Block for BizTalk Server 2004’ section of this article.
· Unzip the POC_BTS_LoggingAppBlock.zip file to C:\
· Backup your C:\Program Files\Microsoft BizTalk Server 2004\ BTSNTSvc.exe.config
· Replace the C:\Program Files\Microsoft BizTalk Server 2004\ BTSNTSvc.exe.config file with the version located at C:\POC_BTS_LoggingAppBlock
· Open the C:\POC_BTS_LoggingAppBlock\POC_BTS_LoggingAppBlock.sln
· Re-reference the Logging and Instrumentation Application Block, if necessary. Reference the assembly if you are not interested in stepping through its code, otherwise reference its project. If you reference the project, you will also need to reference the Enterprise Library’s Common and Configuration projects.
· Build the POC_BTS_LoggingAppBlock.sln.
· Deploy the C:\POC_BTS_LoggingAppBlock_BizTalk assembly to BizTalk; the C:\POC_BTS_LoggingAppBlock_Utilities assembly should be installed into the GAC using a post-build event.
· Import the POC_BTS_LoggingAppBlock bindings using the C:\POC_BTS_LoggingAppBlock\POC_BTS_LoggingAppBlock.xml file and the BizTalk Deployment Wizard.
· Make sure that the host instance that will access the configuration files has write access to C:\POC_BTS_LoggingAppBlock; it needs write access because in this sample the Logging and Instrumentation Application Block writes to .log files in this directory and because a file receive location is used in the sample.
· Start the POC_BTS_LoggingAppBlock_BizTalk.LoggingOrchestration using BizTalk Explorer or BizTalk Administration.
· Test the solution by copying and pasting the C:\POC_BTS_LoggingAppBlock\POC_BTS_LoggingAppBlock_BizTalk\ InstanceDoc_LoggingSchema.xml file into the C:\POC_BTS_LoggingAppBlock\POC_BTS_LoggingAppBlock_BizTalk\Inbound directory.
· Note, if you did not use the C:\POC_BTS_LoggingAppBlock\EnterpriseLibrary.snk to sign the Enterprise Library assemblies you will need to update the three .config files in the C:\POC_BTS_LoggingAppBlock\POC_BTS_LoggingAppBlock_BizTalk directory so that each PublicKeyToken=7f82718233b41429 is updated to use the token associated with your .snk.
· Note, the two sample projects POC_BTS_LoggingAppBlock_BizTalk and POC_BTS_LoggingAppBlock_Utilities will be signed with the C:\POC_BTS_LoggingAppBlock\POC_BTS_LoggingAppBlock.snk. If you use a different .snk, you will need to update the included BTSNTSvc.exe.config so that the App Domain assignment settings reference the PublicKeyToken associated with your .snk.
If the test is successful you will see two entries in the Application event log from the Enterprise Library Logging event source and two entries in the C:\POC_BTS_LoggingAppBlock\POC_BTS_LoggingAppBlock_BizTalk\info.log file.
If the test does not appear to be successful, examine the Application Event Log for errors an Enterprise Library [VariousNamesHere] event source. You can also step through its code by setting a breakpoint in its source code and attached the VS.NET debugger. You will need to reference the Logging and Instrumentation Application Block, the Configuration Application Block and the Enterprise Libarary’s Common project if you are going to step through the Logging and Instrumentation Application Block’s code.
Issues Observed During Research
Application Event Log Entries
· “Failed to fire the WMI event 'LoggingLogWrittenEvent'. Exception: System.Exception: This schema for this assembly has not been registered with WMI.”
o This appeared to be related to not running Install Services on the signed version of the assemblies; to fix this:
- Uninstall the Enterprise Library assemblies from the GAC.
- Uninstall Services
- Rebuild the Enterprise Library
- Move the assemblies to the Enterprise Library bin directory
- Install the Enterprise Library assemblies into the GAC
- Install Services
· “Failed to create instances of performance counter 'Client: # of Logs Written/Sec' - Couldn't get process information from remote machine.”
- I had to add the BizTalk service account, for the host instance that was hosting the orchestration, to the local ‘Performance Monitors Users’ group
· “Failed to create instances of performance counter 'Distributor: # of Logs Distributed/Sec' - Couldn't get process information from remote machine.” Event log entry
o I had to add the BizTalk service account, for the host instance that was hosting the orchestration, to the local ‘Performance Monitors Users’ group
· “Could not create Microsoft.Practices.EnterpriseLibrary.Configuration.ConfigurationManagerSectionHandler, Microsoft.Practices.EnterpriseLibrary.Configuration, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null.”
o I did not build the Enterprise Library Configuration application against the signed version of the Application Block’s assemblies so it did not use a key token when creating new configuration files; once I built the Enterprise Library Configuration against the signed assemblies, the new Enterprise Library Configuration assembly needed to be moved to the Enterprise Library’s bin directory.
Other
- On multiple occasions I was unable to debug the GAC’ed version of the Enterprise Library assemblies
- I never determined a definitive reason for this (obviously things got ‘out-of-sync’) but these steps always cleared it up:
- Uninstall the Enterprise Library assemblies from the GAC.
- Uninstall Services
- Rebuild the Enterprise Library
- Move the assemblies to the Enterprise Library bin directory
- Install the Enterprise Library assemblies into the GAC
- Install Services
Potential Constraints/Concerns of Using the Logging and Instrumentation Application Block in BizTalk Server 2004
- Inability to use the Tracer() class in orchestration because it is not [Serializable] and it uses some thread-relative storage mechanism internally:
- More investigation is necessary
- In any case, XLANG/s does not support C# ‘using’ statement (the ‘using’ statement related to Dispose().)
- However, BAM supports this type of ‘tracing’.
- Inability to use the out-of-the-box classes that implement IExtraInformationProvider for context information because they are not Serializable.
- However, custom implementations of IExtraInformationProvider can be created.
- Start up time takes several seconds the first time the Logging and Instrumentation Application Block is accessed.
- Consider using a command message and/or an orchestration that calls the Logging and Instrumentation Application Block prior to its usage in ‘real’ applications, if this is a problem for you.
- Time lag between changing logging configuration and seeing the configuration changes reflected in the output takes a few seconds.
- No performance or load testing was performed during the POC work on using the Logging and Instrumentation Application Block with BizTalk Server 2004.
- There may be issues associated with Application Domain assignment in BizTalk Server 2004; this does not appear to be a well-known feature.
- Although configuration can be partitioned by assembly using BizTalk’s App Domain assignment feature, this may not be granular enough for you needs, if you have many orchestrations in a single assembly.
Other Constraints/Concerns
- None of the other Enterprise Library Application Blocks were used in my research; however the Logging and Instrumentation Application Block does use the Configuration Application Block to retrieve its configuration data.
- I have not dealt with a server deployment of the Enterprise Library and this article only briefly mentions how a server deployment is different from a deployment where Visual Studio.NET 2003 is installed.
- I have only tested this sample on one Windows Server 2003 system. I expect there to be minor issues with the sample, this document and using the Logging and Instrumentation Application Block from BizTalk Server 2004.
Next Steps
I will post updates, issues and tips on the Logging and Instrumentation Application Block in BizTalk Server 2004 as I work with it more. These will be posted on my blog (see below) as they become available.
Feedback
I am very interested in hearing about your experiences with using the Logging and Instrumentation Application Block in BizTalk Server 2004.
If you have any issues with the sample or using the Logging and Instrumentation Application Block in BizTalk Server 2004, please let me know by contacting me through this blog.