BBCRM SDK – Troubleshooting, Debugging, and Investigating

May 1, 2018

If you’re starting out customizing BBCRM, or even if you’ve been doing so for several years, it’s not unusual to run into frustrations that you feel should be solvable, but that you can’t find a ready answer for among the excellent BBCRM customization resources already out there.  If you’re not already aware, the website provides a great technical reference along with a reasonably well-trafficked Q&A site.  Even so, sometimes it’s hard to find the answer you’re looking for.

This blog introduces a series of posts with practical advice and guidance based on real-world customization development and several years of questions from BBCRM SDK trainings I’ve conducted. Please feel free to contact me if I can clarify or explain any of this–or if you’ve found alternative ways to address the topic.

Reverse Engineering

  • When trying to understand how an existing feature works, first use design mode to view the XML behind the spec:
  • When trying to understand what SQL is running when a given feature is executed within CRM, run SQL Profiler before executing the feature.
    • These are some quick SQL Profiler settings that will filter out some of the irrelevant trace entries:
    • Pause the trace, get ready to trigger the feature you want to investigate, run the trace, trigger the feature (e.g. view a datalist or save a new record), then stop the trace. This limits the amount of data you have to scroll through.

 Debugging CLR Code

  • To debug CLR code—including CLR spec implementations and/or business processes running .NET code—take the following steps:
    • Ensure the code in your Visual Studio IDE is the same code deployed to CRM. Debugging won’t work unless the code is the same code in the DLL running in CRM.
    • If your developer environment has User Access Control enabled (i.e. you have to run processes “As Administrator” to gain administrator permissions), you’ll need to restart Visual Studio as an administrator since by default a standard user is not able to attach a debugger to the IIS worker process.
    • Set a breakpoint in your code and go to “Debug -> Attach to Process”:
    • Check the “Show process from all users” flag and find “w3wp.exe” process (there might be multiple w3wp.exe processes if you are running multiple IIS applications—in that case you can highlight all w3wp.exe processes):
  • Press “Attach” and run the code (via the front-end) you would like to catch in the debugger.  Note the breakpoint in your code will have a solid red circle if the code loaded into CRM reflects the code loaded in your IDE, if instead you have an unfilled red circle with a warning icon this means the debugger is not attached to a process running the code with the breakpoint.  This can be due to mismatched code (i.e. code in process doesn’t match code the code with the breakpoint) or attaching to the wrong process.
  • You should see the IDE stop at the breakpoint:
  • When you’re done debugging, the recommended way to detach is to use “Debug -> Detach All”:

 Embedded Resources

  • If a feature is not available in “Catalog Browser” for a DLL you have copied to the application server, a very common cause for this is due to not setting the “Embedded Resource” property on the file within the Visual Studio project. Double-check (and triple-check) this property by selecting the file within “Solution Explorer” and viewing the properties:
  • This applies to all XML and RDL files.
  • CLR files (*.vb and *.cs) and HTML/JSS/CSS files (*.html, *.js, *.css) do NOT have to be embedded within their respective projects.

 CRM Application Caching

  • The CRM application is aggressive about caching spec metadata (i.e. XML) so that it doesn’t have to reload the spec XML from the catalog every time a user requests a feature. This can cause confusion when developing new features because changes made and loaded via “Load Spec” do not appear in the front-end application.  There are a few ways to address this:
    • Set the MAX_METADATA_CACHE_SECONDS web.config key to 0 (only do this in developer environments as it will negatively affect performance in production or multi-user environments):
    • When making a change on a page that doesn’t appear to be immediately surfacing, open “Design Mode”, open the “Properties” for some page-level feature (e.g. “Edit tabs”), and press “Save” without making any changes—this forces a cache reload for the page:
    • For a guaranteed reload of the server-side cache, run “iisreset” from a command prompt. This can be a little more time-consuming, but is sure to flush anything from the server-side cache.

 SSRS Troubleshooting

  • To troubleshoot SSRS errors where you are seeing vague error messages such as:
    • Execute the report from the machine running the SSRS front-end:

 Event Viewer

  • When troubleshooting unhandled exceptions, check the “Event Viewer” on the app server where the unhandled exception occurred—unhandled exceptions get logged here.
Omatic Software
Omatic Software is dedicated to integrating disparate systems and democratizing data access for today’s nonprofits. Founded in 2002, Omatic has worked with thousands of nonprofits globally to remove their data barriers by integrating systems and enabling nonprofit teams to leverage their donor data rather than be burdened by it. The Omatic team has one goal – unleashing the power of data to show a complete view of your donor, enabling data-driven decision making and opportunity creation for your organization.