Tracing an eConnect .NET application

When using eConnect with your .NET application, you might want to use tracing to monitor the execution of your application. The classes in the Microsoft.Dynamics.GP.eConnect namespace support .NET tracing.

To enable tracing, you add the eConnectTraceSource and trace listeners to the application configuration file. The configuration file you update depends upon whether you are using a reference to the Microsoft.Dynamics.GP.eConnect assembly or a service reference to the eConnect Integration Service.

[spacer]

Reference type

Configuration file

Description

Reference

<ApplicationName>.exe.config

Add the trace source and listeners to the application configuration file of your application.

Service reference

Microsoft.Dynamics.GP.eConnect.Service.exe.config

Add the trace source and listeners to the configuration file of the eConnect Integration Service. The configuration file for the service is typically found in the folder C:\Program Files\Microsoft Dynamics\eConnect 11.0\Service


When you add eConnectTraceSource to the configuration file, the eConnect .NET interface generates trace messages that can be collected and recorded in specified logs, or files.

To collect and record tracing information, you must specify the type of output you want to record. The eConnect trace source has a property named switchValue that you use to specify the type of tracing data to collect. Set switchValue to one of the following values.

[spacer]

switchValue

Description

Error

All exceptions are recorded.

Information

Records important and successful milestones of application execution regardless of whether the application is working properly or not.

Off

Disable tracing for the application.

Verbose

Records events that mark successful milestones. Includes low level events for both user code and the service. Useful for debugging or for application optimization.


Tracing in eConnect supports the same trace listeners as other .NET applications. A trace listener is the mechanism that collects and records trace information. To specify where trace information is recorded, use one of the following trace listeners.

[spacer]

Name

Description

ConsoleTraceListener

Directs tracing output to either the standard output or the standard error stream.

DelimitedListTraceListener

Directs tracing output to a text writer, such as a stream writer, or to a stream, such as a file stream. The trace output is in a delimited text format that uses a specified delimiter.

EventLogTraceListener

Directs tracing output to a specified event log.

TextWriterTraceListener

Directs output to an instance of the TextWriter class or to anything that is a Stream class. It can also write to the console or to a file.

XmlWriterTraceListener

Directs tracing output as XML-encoded data to a TextWriter or to a Stream, such as a FileStream. Typically, output is recorded in an XML file.


The most commonly used trace listeners are the TextWriterTraceListener and the XmlWriterTraceListener. These listeners record trace information to a file. For more information about these or the other trace listeners, refer to the documentation for the .NET framework.

For information about how to get tracing information from the eConnect Integration Service, see eConnect Integration Service tracing in the Troubleshooting section of the eConnect Installation and Administration Guide.

The following steps show how to add tracing to an eConnect .NET application. To begin, open the configuration file in a text editor.

Before you edit the Microsoft.Dynamics.GP.eConnnect.Service.exe.config file, make a copy of the file and store the file in a safe location. If you encounter problems with the service, use the saved copy to restore the existing service configuration.


Adding a trace source

To enable eConnect tracing, add a trace source named eConnectTraceSource to the system. diagnostics section of the configuration file. Use the switchValue attribute of the source to specify the type of information you want logged. The eConnectTraceSource logs trace information that is available in the classes and methods of the Microsoft.Dynamics.GP.eConnect namespace.

Typically, the Microsoft.Dynamics.GP.eConnect.Service.exe.config file includes the eConnectTraceSource. To enable tracing, change the switchValue of the eConnectTraceSource to Error, Information, or Verbose.

The following XML example adds the eConnectTraceSource to an application configuration file. Notice how switchValue is set to Verbose.

<system.diagnostics>
	<sources>
		<source name="eConnectTraceSource"
switchValue="Verbose">
	</source>
	<trace autoflush="true" />
</system.diagnostics>

Adding listeners

Add the listener you want to use to log the trace results. Add a <sharedListeners> node to the <system.diagnostics> section of you application file. Add and configure the listeners you want to use.

Typically, the Microsoft.Dynamics.GP.eConnect.Service.exe.config file includes listeners. Update the initializeData attribute of the eConnectTextTracelistener or the eConnectXmlTracelistener to specify a folder and file name for the trace file.

The following XML example shows how to add a shared listener to your application configuration file. Notice how a TextWriterTraceListener is specified. The intializeData attribute specifies the location and name of the log file.

<sharedListeners>
	<add initializeData="c:\TEMP\eConnect.log"
		type="System.Diagnostics.TextWriterTraceListener, 
		System, Version=2.0.0.0, Culture=neutral,
		PublicKeyToken=b77a5c561934e089"
		name="eConnectTextTracelistener">
			<filter type="" />
	</add>
</sharedListeners>

Adding a listener to the source

To use the listener, add the listener to the listeners of the eConnectTraceSource. Specify the name of the listener you added to the SharedListeners.

Typically, the Microsoft.Dynamics.GP.eConnect.Service.exe.config file includes a listener named eConnectTextTracelistener with the eConnectTraceSource. You do not need to make any changes to use this listener. To use the eConnectXmlTracelistener, add that listener to listeners node of the eConnectTraceSource.

The following XML example adds the shared listener named eConnectTextTracelistener to the eConnectTraceSource in an application configuration file.

<source name="eConnectTraceSource" switchValue="Verbose">
	<listeners>
		<add name="eConnectTextTracelistener">
			<filter type="" />
		</add>
	</listeners>
</source>

Collecting trace data

Save the changes to the application configuration file. If you made change to the Microsoft.Dynamics.GP.eConnect.Service.exe.config, stop and restart the eConnect Integration Service.

To generate trace data, start your application and perform the operations you want to trace. To view the result, open the specified log or file and review the trace information.

Stopping the trace

When you are done collecting trace information. You should disable the eConnectTraceSource. In the configuration file, set the switchValue attribute of the eConnectTraceSource to Off.

<source name="eConnectTraceSource" switchValue="Off">

Example

The following XML example shows the system.diagnostics node from an application configuration file. Notice how eConnectTraceSource has been added with a switchValue set to Verbose. Also notice how two listeners have been specified for eConnectTraceSource. The eConnectTextTraceListener logs trace information as text to a file name eConnect.log. The eConnectXmlTracelistener logs trace information as XML in a file named eConnectLog.xml.

<system.diagnostics>
	<sources>
		<source name="eConnectTraceSource"
switchValue="Verbose">
			<listeners>
				<add name="eConnectXmlTracelistener">
					<filter type="" />
				</add>
				<add name="eConnectTextTracelistener">
					<filter type="" />
				</add>
			</listeners>
		</source>
	</sources>
	<sharedListeners>
		<add initializeData="c:\TEMP\eConnect.log"
			type="System.Diagnostics.TextWriterTraceListener, 
			System, Version=2.0.0.0, Culture=neutral,
			PublicKeyToken=b77a5c561934e089"
			name="eConnectTextTracelistener">
				<filter type="" />
		</add>
		<add initializeData="c:\TEMP\eConnectLog.xml"
			type="System.Diagnostics.XmlWriterTraceListener, 
			System, Version=2.0.0.0, Culture=neutral,
			PublicKeyToken=b77a5c561934e089"
			name="eConnectXmlTracelistener">
				<filter type="" />
		</add>
	</sharedListeners>
	<trace autoflush="true" />
</system.diagnostics>


Documentation Feedback