Monday, 25 April 2016

Debug Acumatica Code

Hi All,

Today I want share with you one great way to make you development on Acumatica Platform better and faster - debug Acumatica source code.

This can give you unlimited ability to:
  • Investigate existing logic
  • Planing and develop customization
  • Understanding what code can be reused
  • Analyzing issues
  • Do performance tests
Important Note: This approach works only on latest version of Acumatica ERP 5.3 Update 5 (Version number 5.30.1583)

Welcome into the article, if you interesting in details.
Installation
First of all you need to install Acumatica with debugger tools:

In general, these debugger tools are just additional PDB files that will be copied to bin folder of Acumatica web site. You can see all these files there when installation is finished.
A program database (PDB) file holds debugging and project state information that allows incremental linking of a Debug configuration of your program. In general PDB files contains link between compiler instructions and some lines in source code.

Folder "Acumatica ERP\Files" is a special system folder that contains original copy of Acumatica Application. Every time when you install or upgrade any Acumatica instance, Configuration Wizard will copy data from this folder to replace instance files. These files will not be copied to any instance automatically. But to be able to debug Acumatica, you must have them in every instance that you need to debug. 

So to distribute these PDB files, you can:
  • Install new instance
  • Upgrade existing one.
  • Copy files manually

Note that DLLs and PDBs should be from the same version of Acuamtica, so you are not able to copy PDB from 5.3 Update 5 to 5.3 update 4 and use it for debugging.

IF you want to copy files manually, note that most important files are:
  • PX.Data.pdb (PDB for PX.Data.dll) - platform core code
  • PX.Objects.pdb (PDB for PX.Objects.dll) - erp business logic
For my example, I will create a new site with name "Acumatica Debug" and insert a demo data there. You do not need to do any additional steps during this installation, so just install an instance the same way how you do it usually.

Configuration
When instance is ready, you have to do one more step for better debugging - go to the web.config file and set debug option for compilation section.

<compilation debug="True" defaultLanguage="c#" targetFramework="4.5.1">
Acumatica may not set this property automatically, so you have to make sure that it is there. When you set is once, than Acumatica will always keep it there during upgrades.

Warning: Be careful with this option on production environment, as debug configuration can significantly slow down Acumatica performance.

Opening Visual Studio
First of all you need to have a Visual Studio. You may use any version starting from VS 2010, but note that for Acumatica 5.3 we are using VS 2015, so you may see some C# 6.0 features in the code. So Visual Studio 2015 is recommended version here.

Using Visual Studio, you should go to  File -> Open -> Web Site menu and select folder with your website. If you have any customization project, you may want to open extension library project.

Also you need to configure VS to debug not only your code:
Another setting that may want to do is to specify path for PDB files:

Browsing Code
You know that Acumatica has open source code and you can easily check it with Acumatica Customization Manager. Especially for using from Visual Studio, Acumatica contains source code on the file system that you can use  for search. All sources are located in "<SiteFolder>\App_Data\CodeRepository\" folder.
Use search to find "Batch_RowSelected" event handler in Journal Entry graph. To search through Acumatica sources, you need to specify "Entire Solution" search option.

And finally set a breakpoints there.

Attaching Debugger
In the last step you need to attach your debugger to running IIS process. To do this you can use "Attach to Process" button under Debug menu. You can check more guidance here.
Select all w3wp.exe processes and click Attach. If you do not see w3wp.exe, that restart visual studio under administrator and select "Show processes from all users" checkbox.

Be patient, loading of symbols may take some time. In my case it was several minutes.
Make sure that breakpoints is red and there is not errors. If point has any warnings, you check
  • That Acumatica instance is running
  • PDB files for each dll that you want to debug are there in bin folder.
  • PDB files are the same version as DLL
If nothing helps, you can try to load symbols manually. Here you can find great manual.

Finally you can run Acumatica business logic and debug sources.

Use the standard approach for debugging and you will be able save a lot of time for customization development.

Acumatica supports debugging of some parts of core platform (PX.Data) but there is one small issue in the version that I used, so I was not able to debug PX.Data.dll part. But it will be fixed in new updates of Acumatica.


This is very powerful feature, use it! And have a nice debugging!

4 comments:

Hari Eko said...

Hi Sergey,

How to get PX.Objects.pdb file
After I was created new instance and then checking in Bin folder, I didn't see PX.Objects.pdb file.

Sergey Marenich said...

Dear Hari,

Please make sure that you are using version 5.30.1583.
Also make sure that you have installed Acumatica with debugging tools and updated your instance to the latest version.

dangminhhuynh said...

Hi Sergey,
Should we install same version for each acumatica instance for debug it?

Sergey Marenich said...

Hi Dang,

When you want to install PDB files, you should have the same version of installer.
But upon it is installed, you can use different versions of installer, as PDB files are already uploaded to bin folder.