cub-e.net

just coding...

Using ITracingService in Microsoft Dynamics CRM plugins

The ITracingService interface provides a way to log plug-in run-time information. This method of logging information is especially useful for sandboxed plug-ins registered with Microsoft Dynamics CRM Online that cannot otherwise be debugged using a debugger.  It was introduced in CRM 2011.

Tracing assists developers by recording run-time custom information as an aid in diagnosing the cause of code failures. Tracing is especially useful to troubleshoot Microsoft Dynamics CRM Online registered custom code as it is the only supported troubleshooting method for that scenario. Tracing is supported for sandboxed (partial trust) and full trust registered custom code and during synchronous or asynchronous execution. Tracing isn’t supported for custom code that executes in Microsoft Dynamics CRM for Outlook or another mobile client.

The tracing information is displayed in a dialog of the Microsoft Dynamics CRM Web application or in the event log for on-premise deployments, only if an exception is passed from a plug-in back to the platform.  However, starting with CRM Online 2015 Update 1, a trace logging feature was introduced that records tracing information even when an error does not occur.

Logging and tracing


An alternative method to troubleshoot a plug-in or custom workflow activity (custom code), compared to debugging in Microsoft Visual Studio, is to use tracing. Tracing assists developers by recording run-time custom information as an aid in diagnosing the cause of code failures. Tracing is especially useful to troubleshoot Microsoft Dynamics 365 (online) registered custom code as it is the only supported troubleshooting method for that scenario. Tracing is supported for sandboxed (partial trust) and full trust registered custom code and during synchronous or asynchronous execution. Tracing isn’t supported for custom code that executes in Microsoft Dynamics 365 for Outlook or another mobile client.

Recording of run-time tracing information for Microsoft Dynamics 365 is provided by a service named ITracingService. Information provided to this service by custom code can be recorded in three different places as identified here.

  • Trace log
    Trace log records of type PluginTraceLog can be found in the web application by navigating to Settings and choosing the Plug-in Trace Log tile. The tile is only visible if you have access to the trace log entity records in your assigned security role. Writing of these records is controlled by the trace settings mentioned in the next section. For information on required privileges for the PluginTraceLog entity, see Privileges by entity.
  • Error dialog
    Asynchronous registered plug-in or custom workflow activity that returns an exception back to the platform results in an error dialog box in the web application presented to the logged on user. The user may select the Download Log File button in the dialog to view the log containing exception and trace output.
  • System job
    For asynchronous registered plug-in or custom workflow activities that returns an exception, the tracing information is shown in the Details area of the System Job form in the web application.

Enable trace logging:


To enable trace logging in an organization that supports this feature, in the web application navigate to Settings > Administration> System Settings. In the Customization tab, locate the drop-down menu labeled Enable logging to plug-in trace log and select one of the available options. 

Option

Description

Off

Writing to the trace log is disabled. No PluginTraceLog records will be created. However, custom code can still call the Trace method even though no log is written.

Exceptions

Trace information is written to the log if an exception is passed back to the platform from custom code. 

All

Trace information is written to the log upon code completion or an exception is passed back to the platform from the custom code.


If the trace logging setting is set to Exception and your custom code returns an exception back to the platform, a trace log record is created and tracing information is also written to one other location. For custom code that executes synchronously, the information is presented to the user in an error dialog box, otherwise, for asynchronous code, the information is written to the related system job.

By default, the System Administrator and System Customizer roles have the required privileges to change the trace logging setting, which is stored in a TraceSettings entity record. Trace settings have an organization scope.


Writing to the trace service from a Plug-in:

Before writing to the tracing service, you must first extract the tracing service object from the passed execution context. Afterward, simply add Trace calls to your custom code where appropriate passing any relevant diagnostic information in that method call.

//Extract the tracing service for use in debugging sandboxed plug-ins.

ITracingService tracingService =

    (ITracingService)serviceProvider.GetService(typeof(ITracingService));

// Obtain the execution context from the service provider.

IPluginExecutionContext context = (IPluginExecutionContext)

    serviceProvider.GetService(typeof(IPluginExecutionContext));

// For this sample, execute the plug-in code only while the client is online.

tracingService.Trace("AdvancedPlugin: Verifying the client is not offline.");

if (context.IsExecutingOffline || context.IsOfflinePlayback)

    return;

// The InputParameters collection contains all the data passed

// in the message request.

if (context.InputParameters.Contains("Target") &&

    context.InputParameters["Target"is Entity)

{

    // Obtain the target entity from the Input Parameters.

    tracingService.Trace

        ("AdvancedPlugin: Getting the target entity from Input Parameters.");

    Entity entity = (Entity)context.InputParameters["Target"];

 

    // Obtain the image entity from the Pre Entity Images.

    tracingService.Trace

        ("AdvancedPlugin: Getting image entity from PreEntityImages.");

    Entity image = (Entity)context.PreEntityImages["Target"];

}


References:

·  ITracingService Interface - https://msdn.microsoft.com/en-us/library/microsoft.xrm.sdk.itracingservice.aspx

·  Debug a plug-In - https://msdn.microsoft.com/en-us/library/gg328574.aspx

·  Sample: Web access from a sandboxed plug-in - https://msdn.microsoft.com/en-us/library/gg509030.aspx
·  Sample: Calculate Price plug-in - https://msdn.microsoft.com/en-us/library/dn817877.aspx

Loading