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

 

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:

  1. On the computer running Microsoft Dynamics CRM for Outlook, click Start, click All Programs, click Microsoft Dynamics CRM <version>, and then click Diagnostics.

  2. Click the Advanced Troubleshooting tab, and then select Tracing to enable or click to clear Tracing to disable.

  3. 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:

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.

 

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:

  1. Click File > Options

  2. Click Customize Ribbon

  3. Under the Customize the Ribbon area, mark the Developer checkbox

 

After enables this ribbon tab:

  1. Open the desired item (i.e. contact)

  2. Hits Design This Form button

  3. Select the (All Fields) tab

  4. Choose the User-defined fields in this item menu option from the Select from drop-down menu

 

By using the Outlook grid view is useful for Side by Side comparison and allows the sorting by fields.

  1. For Outlook grid view:

  2. Click-right in the grid view

  3. Select Field Chooser option

  4. Add the desired columns (i.e. crmid or crmLinkState)

  5. Use these new columns on the grid view or the search options

References

How to enable tracing in Microsoft Dynamics CRM

How to enable tracing for the Microsoft Dynamics CRM for Outlook client 

Monitor and troubleshoot Microsoft Dynamics CRM 

Enable tracing for Microsoft Dynamics CRM for Outlook 

Event Tracing 

Event Tracing for Windows (ETW) Simplified 

SQL Server Profiler 

Fiddler 

Fiddler Timers 

MFCMAPI 

MFCMAPI demonstrates MAPI client code 

EWSEditor 

SQL Server Compact & SQLite Toolbox