Use ITracingService in Plug-ins

Category: Maintainability, Supportability

Impact potential: Medium

Symptoms

Debugging and/or troubleshooting plug-in issues or behaviors are complicated without rich and insightful logging or tracing.

Guidance

The ITracingService interface assists developers by recording run-time custom information as an aid in diagnosing the cause of code failures or unexpected behavior in plug-ins. Before writing to the tracing service, you must first extract the tracing service object from the passed execution context. Afterwards, simply add Trace calls to your custom code where appropriate passing any relevant diagnostic information in that method call.

Note

Trace logging using ITracingService interface works only when the plug-in is registered in Sandbox mode and you must enable trace logging to get run-time data. For more information see: Logging and tracing

//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"];
}

Additional information

Tracing is especially useful to troubleshoot 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 other mobile client.

See also

Write a plug-in
Tracing and logging