Dynamics CRM Outlook client: Simple list of Troubleshooting Tools

Gustavo Longo

Like ( 0 )

Report

About the series

This series will introduce you to two major areas related to Outlook Synchronization in Microsoft Dynamics CRM for Outlook:

Concepts & Rules

Troubleshooting

Dynamics CRM Outlook client: Highlights and Simple Methodology for troubleshooting
Dynamics CRM Outlook client: Simple list of Troubleshooting Tools
Dynamics CRM Outlook client: Synchronization Scenarios - Changes to items in Outlook (ACT)
Dynamics CRM Outlook client: Synchronization Scenarios - Changes to items in Dynamics CRM (ACT)
Dynamics CRM Outlook client: Synchronization Scenarios - Track an item in Outlook (ACT)
Dynamics CRM Outlook client: Synchronization Scenarios - Merging overlapping changes

Introduction

In order to further understand the troubleshooting of the Outlook Synchronization, let’s look at a simple list of troubleshooting tools.

Follow below a quick summary of this list:

Platform traces/CRM client traces
ETW Tracing
SQL Profiler
Fiddler
MFCMAPI/EWSEditor
SQL CE Toolbox
Outlook Add-in user interface errors
Developer tools/Outlook grid view

Platform traces/CRM client traces

Microsoft Dynamics CRM lets you create trace files that monitor the actions that are performed by Microsoft CRM. Trace files are helpful when you need to troubleshoot error messages or other issues in Microsoft CRM.

When you are being able to understand traces at a fundamental level is a critical support and debugging skill.

The trace provides contextual information to the problem and can offer hints at what to look at next and the searches based on call stack behavior and exception details are more accurate in locating the right fix.

Remember some important concepts about the anatomy of a trace:

Logged output of the call stacks for all threads that were running while tracing was enabled.
A call stack is a sequential output of the code execution path relative to the instructions being performed by a specific thread.
A thread is a unique instance of a set of instructions that carry out a specific task.

Notice a trace sample:

In general, you can create unmanaged and managed trace files.

Let’s focus on CRM client traces and review some examples of the trace file types:

OUTLOOK-Client

Managed Code Execution log (.Net - C#)

crmaddin-<date>

Unmanaged Code Execution log (Native - C++)

Enable or disable tracing for Microsoft Dynamics CRM for Outlook:

On the computer running Microsoft Dynamics CRM for Outlook, click Start, click All Programs, click Microsoft Dynamics CRM <version>, and then click Diagnostics.
Click the Advanced Troubleshooting tab, and then select Tracing to enable or click to clear Tracing to disable.
Click Save.

Using the Windows Registry, follow below the related entries:

HKCU\Software\Microsoft\MSCRMClient:

TraceEnabled
TraceRefresh

Optional Entries:

TraceCategories (Error by default)
TraceCallStack (Enabled by default)

Traces Located:

%localappdata%\Microsoft\MSCRM\Traces

Caution:

The above info tells you how to modify the registry. However, serious problems might occur if you modify the registry incorrectly. Therefore, make sure that you follow these steps carefully. For added protection, back up the registry before you modify it. Then, you can restore the registry if a problem occurs. For more information about how to back up and restore the registry, click the following article number to view the article in the Microsoft Knowledge Base: How to back up and restore the registry in Windows.

ETW Tracing

Quick summary about the Event Tracing for Windows (ETW):

Used by the OS and many apps for diagnostic tracing
Allows for correlation of events across different components (CPU/IO/etc)
High performance tracing, can handle large volumes of events
Trace files use .etl extension – binary format
Requires tooling for processing/viewing trace files

When you enable tracing via the diagnostics tool, this enables ETW tracing as well. Trace files can be found under MSCRM\Traces along with the standard client logs. Note that you need to shutdown Outlook to cleanly stop a trace session before accessing traces.

The following registry keys control automatic ETW tracing:

[HKCU\Software\Microsoft\MSCRMClient]

Key	Type	Description
EtwTraceEnabled	REG_DWORD	Set to 1 to enable automatic ETW tracing
EtwEnabled	REG_DWORD	Set to 1 to enable PerfMarker events in the ETW trace
EtwTraceLevel	REG_DWORD	(optional) Controls the trace logging level (from 0 to 255, 255 is the most verbose). Default is 255. Recommended that this value is not changed.
EtwTraceFlags	REG_QWORD	(optional) Controls the tracing flags. These can be used to filter out undesired event types. This is a bitmask of the following values: 0x00000001 – PerfMarker 0x00000002 – ServerCall 0x00000004 – SqlCe 0x00000008 – ClientCache 0x00000010 – RibbonX 0x00000020 – MapiStore 0x00000040 – OutlookSync 0x00000080 – OutlookEmailTagger 0x00000100 – OutlookOfflineSync 0x00000200 – OutlookBackgroundEmail The default is to log all event types. If you need to log for long durations, you can greatly reduce the log file sizes by omitting logging of PerfMarker and SqlCe events. Otherwise you should not modify this key.

Caution:

All ETW events share common attributes, which describe the event:

EventId	Description
Task	All events fall under a task. It’s a logical grouping of related events.
Opcode	Defines the general “operation” being performed for the event. CRM events usually use the system-defined ‘Start’, ‘Stop’, and ‘Info’ opcodes.
ProcessId	Process in which the event occurred
ThreadId	Thread in which the event occurred
TimeStamp	Time at which the event occurred.
Keyword	A set of flags that apply to this event. See notes above for the ‘EtwTraceFlags’ regkey which controls the filtering on event keywords.
Level	‘Verbosity’ level for the event. See notes above for the ‘EtwTraceLevel’ regkey which controls the filtering on event levels.

Follow below the event descriptions for Microsoft Dynamics CRM for Outlook:

EventId range	Category	Description
1	PerfMarker	This is a generic event used to log miscellaneous actions throughout the client.
100-115	OrganizationService webservice	These events record start/stop points for calls to the Organization.svc WCF endpoint.
200-203	Ribbon webservice	The client calls into the ribbon webservice to retrieve ribbon definitions for the client.
300-301	Web browser control navigation	These events record page navigations done via the hosted CRM browser control in Outlook.
400-401	Web request	These represent misc. web requests (usually performed in the background).
500-501	SqlCe	SqlCe commands against local cache databases.
600-607	Client cache	Client cache contains objects retrieved from server and cached locally. SqlCe is used as a local persistent store. Cache misses here will usually result in server calls to retrieve the missing data. Refresh of data in the cache is performed asynchronously.
700-705	RibbonX loader	These events mark calls into the client-side RibbonX cache loader. Calls into the cache loader will usually result in subsequent calls to the ribbon webservice.
800-803	CRM MAPI store	These events record actions done on the Message API (MAPI) store.
900-902	Outlook sync	These events record actions related to Outlook synchronization process.

SQL Profiler

SQL Server Profiler is an interface to create and manage traces and analyze and replay trace results.

Events are saved in a trace file that can later be analyzed or used to replay a specific series of steps when trying to diagnose a problem.

Fiddler

It is a free web debugging proxy which logs all HTTP(s) traffic between the client machine and server. Allow you to inspect incoming and outgoing (requests and responses).

MFCMAPI

MFCMAPI provides access to MAPI stores, connecting in mailbox locally (OST).

The MFCMAPI user interface can display all the folders and the subfolders that are in any message store. It can also display any address book that is loaded in a profile.

Allows for the inspection of MAPI properties of Outlook objects.

A Microsoft Visual C++ Microsoft Foundation Classes (MFC) project, MFCMAPI is designed as a series of MFC dialog boxes that implement a directory hierarchy in the left pane and a property list in the right pane. Every dialog box has several menu items that you can use to act upon the active items.

EWSEditor

Demonstrate the Exchange Web Services Managed API, connecting in mailbox through EWS endpoint.

Demonstrate the Exchange Web Services SOAP traffic.

Assist non-developers in debugging and understanding Exchange stores by exploring items, folders, and their properties in depth.

SQL CE Toolbox

Allows for the inspection of SQL CE databases.

Note: Visual Studio 2012 natively includes functionality to view SQL CE 4.0 databases.

There are standalone versions for SQL CE 3.5 and SQL CE 4.0.

Outlook Add-in user interface errors

By default, if an VSTO (Visual Studio Tools for Office) add-in attempts to manipulate the Microsoft Office user interface (UI) and fails, no error message is displayed.

You can use these messages to help determine why a custom Ribbon does not appear, or why a Ribbon appears but no controls appear.

Microsoft Outlook supports the logging of the communications that occur between Outlook and various types of email servers.

Developer tools/Outlook grid view

The user-defined fields can be viewed using Developer tools or by adding the properties to the Outlook grid view.

For Developer tools:

Click File > Options
Click Customize Ribbon
Under the Customize the Ribbon area, mark the Developer checkbox

6303.4_2D00_2.png

After enables this ribbon tab:

Open the desired item (i.e. contact)
Hits Design This Form button
Select the (All Fields) tab
Choose the User-defined fields in this item menu option from the Select from drop-down menu