Would like to share with you all a tool which I have built for logging in Microsoft Dynamics CRM. The tool works for both CRM 2011 and CRM 2013 versions of on-premise/ IFD/ Office 365 environment. It also gives you the option to perform the log operation in File/ Eventviewer/ Custom Database/ CRM entity as per your choice. And guess what, you can do all this with just a few configuration changes.
As my all other tools, this tool is also available for download at codeplex site URL – https://enterpriselogger.codeplex.com/.
The detailed documentation of this tool is provided in the documentation tab of the codeplex site. Or you can keep reading this blog to understand how the tool works.
Don’t want to go through huge documentation? No worries. The following YouTube links would give you a visual approach about how to use this tool in your CRM Organization.
Introduction to Enterprise Logging tool – http://youtu.be/l2-cbZDcgIo
Event Viewer Logging – http://youtu.be/j-MVx5w16t0
The tool consists of two components. A managed solution which would help in configuration and an assembly which you need to refer from your classes to do the actual logging stuff. Apart from that, there will be an utility which you need to run for the first time after you install the solution. The utility would provide the required privileges to all your security roles in the system to the logging entities to enable smooth functioning of the logging tool.
Lets first focus on the configuration part. After you install the managed solution “Xrm Logger”, open the solution and move to the configuration page of the solution. Please check the below screenshot for the same
You would be presented with the following options:
- 1. Select your installation type and depending on that the logging mechanism would change.
- 2. Enable or disable logging using the “Enable Logging” checkbox.
- 3. Ability to configure logging at individual plugin step level.
- 4. Ability to configure logging at custom workflow assembly level.
Let’s first concentrate on the on-premise/ IFD installation. The moment we select On-Premise/ IFD option, we get the following options for logging as shown in the below screenshot
Each of these options is explained under separate headers below
Once we select File Logging, the users is asked to provide a file path to log. As the message in red suggests, the file can be local to the CRM server or should be accessible over the network from the CRM Server. Also the users of CRM should have write permissions to the file because the logging to this file would be done based on the user’s context from whom the logger utility is invoked.
I have entered D:\Logging\Logger.txt as the log file path and saved. Please check for the screenshot below.
Once you have configured your logging, let us now concentrate on the other part of it. The second component of this tool is the Xrm.Logging.dll which you need to refer in your plugins/ custom workflow assemblies/ custom applications or any application through which you are interacting with CRM. I have created a sample plugin project for demo and have referenced the DLL in the project. Please check for the screenshot below.
Once you are refer it, include the namespace “Xrm.Logging” in your plugin project and you are ready to use the logger in your code.
The logger dll gives you option to log errors/ warnings and messages. Lets first explore the parameters that are required for logging an error. For that we invoke the method TraceHelper.LogError.
To generate an error, I am forcibly calling the Retrieve of account on any arbitrary GUID. Hence it would throw an error. The entire code is shown in the screenshot below.
The LogError method has two overloads for FaultException and General Exception respectively. Use the parameters as per the documentation which is very detailed and also suggests when to use what as you can see from the screenshot above. As you can see the logger provides you an option to also show custom error message to the business user and also an option whether to pass the exception back to the user. So in the above example, the detailed error would get logged in the Logger.txt file and the business user would get a pop-up which would show “custom error message”. Now we also have an option to suppress the exception setting the “passExceptionToUser” as false. In that case the system would not throw the error back to the user. By default if you do not specify the parameter it would be set to true.
Once we are done with the code, build the plugins project. Now before regsitering, we first have to merge the Xrm.Logging.dll and Plugins dll. You can do it from the command prompt using the ILMerger.exe utility or using the ILMege tool from codeplex. Personally I prefer to use the latter as it is wonderful tool and you do not need to remember all the parameters that you need for merging. The tool is available for download at: http://ilmergegui.codeplex.com/
As you can see I have added the Plugin and the Logging assembly and have selected my plugin assembly as the Primary assembly (check the checkbox beside the assembly to select the primary assembly). Next select “Sign with Key File” option and choose the strong name key that you used to sign your plugin assembly. Put the path for the merged file output. Choose the debug option as true in case you need to debug the merged assembly.
Now register the merged dll in the plugin registration tool and add the required steps. I have registered the plugin to fire on the account-precreate. Now when i try to create an account the following is the screenshot I get.
We get Business Process Error and as you can see, the custom error message is shown to the user. Now let us open the Logger.txt file.
The detailed error is logged in the text file. One big advantage of using the logging solution is it gets the entire stack of error message i.e it parses through the entire inner exception of the exception object.
Now say you want to log an exception in the text file but you do not want to show the message to the user or in other words you want to suppress the error. I will just come to the code and set the parameter passExceptionToUser:false. Check for the screen shot below.
Now when we create the account, the account is now created successfully in-spite of the exception. However the error message is still logged in the logger file.
Now say you want to disable logging for the account pre-create step altogether. No need to change any code. All you need to do is go back to the solution and uncheck the checkbox for the plugin step and save. Check for the screenshot below.
Now even though you have logging code, it would simply bypass and not log anything. Similarly you could use the LogMessage and LogWarning to log messages and warnings respectively.
P.S – The logging configuration for plugins and workflows would only be respected if you pass the optional parameter of plugincontext or workflow context depending from where you are calling. If you do not pass the parameter in the logging method, it would always log even if you disable logging for the step.
Now we would move to Event Viewer logging. To see how it works, please follow this link – https://debajitcrm.wordpress.com/2014/06/26/logging-in-eventviewer-with-enterprise-crm-logger/