D365 Debug Tutorial #2

D365 Debug Tutorials

If you have not seen them already, please feel free to check out my previously written D365 debug tutorials. While each article can stand on its own, following these in order may be helpful from a teaching and learning perspective.

D365 Debug Tutorial #1

Before getting into this D365 debug tutorial example, make sure you are familiar with the basics. If you are new to debugging or need a review, please read my article on How To Debug D365 and How To Debug Part 2.

Diagnosing A Problem

While most of the articles I write explain how to build something new, this series of articles are different.

In this D365 debug tutorial, the goal is to teach you how to diagnose a problem. There are several different approaches you can take to understanding the cause of a problem. This series of articles is designed to teach you those different approaches.

In order to gain the benefits of these lessons, it is really important that you follow along and practice these steps for yourself. The fact that you don’t likely don’t have this particular error message is unimportant. What is important is that you practice the techniques needed to find the issue.

After you have these techniques, they will help you to solve difficult problems and to do so much quicker.

Practice Problem #2

In this second D365 Debug Tutorial, pretend you are a D365 user working in the Accounts Payable module. You are trying to create a purchase order for a one-time vendor, but you keep receiving an error message. What can you do to fix or workaround the issue?

Replication Steps

In Microsoft Dynamics 365 for Finance and Supply Chain, use a sandbox environment that has the Contoso demo data deployed. Then, change to company to the USP2 company.

First, navigate to Accounts Payable>Purchase Orders>All purchase orders.

Second, click the ‘New‘ button to create a new purchase order.

Third, in the ‘Create purchase order‘ dialog that opens, click the ‘One-time supplier‘ radio button. Notice, an error will be shown, and the radio button will go back to unchecked.

The error message reads: “One-time vendor account specified in the vendor parameters does not exist in the vendor table.“

Exercise: Solve The Problem

By practices the techniques needed to solve a simpler problem, this will allow you to solve much more complex problems.

In this d365 debug tutorial, I recommend you practice four steps:

First, find the line of code that is showing the warning message. Typically this is done by placing breakpoints, and debugging the code.
Second, look at the conditions that surround that message, and determine what data needs to change to cause the system to allow the user to proceed
Third, determine where to navigate in the D365 system to make that data change.
Fourth, find the data on the form that needs modified.

In this example the error message does say clearly what form you need to use to remove the error message. Therefore, you could just jump to step three. However, I recommend you find the code as practices this will be helpful for more complex problems. Additionally, it will help you find which field specifically you need to change on that form.

Find The Code: Find Labels

As I said in the last D365 debug tutorial, and I will keep saying, the easiest way to find most error messages in code is to use the ‘Find Label‘ form using Visual Studio. Let us go through the steps of doing just that.

First, in Visual Studio go to Extensions>Dynamics 365>Find Labels…

Next, type into the ‘Search‘ field the message your seeing in the browser. In this case, the message is “One-time vendor account specified in the vendor parameters does not exist in the vendor table.” Then hit ‘Enter‘ on your keyboard. Tip: Sometimes it is helpful to only type in the first half of the error message.

In this case, we see the label is @SYS57595.

Next, right click on the label in the grid, and select ‘Find References‘.

Find References

After selecting ‘Find References‘, a window will open showing all places in the code that the label is found. Therefore, we no longer need the ‘Label Search‘ window open. Click ‘Cancel‘ to close this window.

Similar to the last example, there is only one result: Tables/VendTable/Methods/createOnTimeAccountValidate.

If there are many results, look through each line and make a guess as to whether you think the result is relevant to the process you performed in the replication steps.

If you are not sure, double click on each result, and add a breakpoint to that line of code. Then, attach the debugger and rerun the replication steps. Whichever breakpoints are hit are relevant to your further research. Any that are not, can be ignored. It does not hurt to add more breakpoints that you need. We will do these steps in a future D365 debug tutorial.

In this case, double click on the only result. Immediately, the code editor opens up, with the cursor on the line of code with the referenced text. Notice, the error message is thrown from the method named ‘createOneTimeAccountValidate‘ on the Table node named VendTable.

Now, the next step is to look at the conditions to determine WHY the error message is being thrown.

Find The Code: Start From The Beginning

Before looking at the conditions, let us look at another way we could have found the code. Perhaps you could not find the error message in the ‘Find Labels’ form. Or, perhaps instead of an error message being shown, a value was changed in an unexpected way. The following steps provide another way of discovering the source of the issue.

In the replication steps of this D365 debug tutorial, the last step we took before the issue occurred was we changed the value of the ‘One-time supplier‘ radio button. As opposed to when saving the record or clicking the ‘Ok‘ button, the error message showed immediately.

Ask yourself: What code runs immediately after you change a value in a form control?

Ultimately, by learning how to develop forms you also learn how to debug them.

The answer is that when a value is changed on a form, the system calls the ‘modified‘ method on the form control, or the ‘modified‘ method on the Datasource field, or the ‘ModifiedField‘ method on the table.

Before we can do that, we need to know the name of the form we are on.

Find The Form Name

Often times when debugging an issue you need to know the name of the form you are on.

To do this, right click anywhere on the form except in a field, then hover over ‘Form information‘.

Notice, a second menu will show the ‘Form Name‘. In this case it is ‘PurchCreateOrder‘.

Find The Form Control

Now that you know the form name, in this D365 debug tutorial we also need to find the form control.

Repeat the steps from the last section, but instead of right clicking anywhere, right click on the label ‘One-time supplier’ just above the radio button that we are modifying. Next, click on the menu ‘Form Name: PurchCreateOrder‘.

On the right side of the browser, a dialog will show all of the ‘Form information‘. This form in extremely helpful, and tells us a lot of information that is helpful when debugging.

First, under ‘Form name‘ we can see again the name of the form is ‘PurchCreateOrder‘.
Second, under ‘Control name‘ we can see that the name of the form control is ‘PurchTable_OneTimeVendor‘
Third, in case we need it, under ‘DataSource‘ the name of the DataSource used by this form control is ‘PurchTable‘.
Fourth, in case we need it, under ‘Data field‘, the name of the field on the DataSource is ‘OneTimeVendor”

Find The Method On The Form Control

Now that we know the name of the form, and the name of the form control, let’s find the code that runs when we modify the ‘One-time supplier’ field in the browser.

First, in Visual Studio, type the name of the form, ‘PurchCreateOrder‘ into the search bar at the top of the Application Explorer, then click ‘Enter‘.

Second, locate the form named ‘PurchCreateOrder‘ in the results. Then, right click on the form and select ‘View Designer‘.

Third, in the designer window that opens, expand nodes until you find the form control named ‘PurchTable_OneTimeVendor‘. Or, for a faster way, type the form contorl in the ‘search’ window at the top of the designer and click enter.

Fourth, click on the arrow to the left of the form control to expand its nodes. Then, do this once more on the ‘Methods’ node.

Unfortunately, there is no overridden ‘modified‘ method like we hoped. Actually, it is quite common for code to NOT be on the form control. So this is actually not surprising. Therefore, we just need to keep looking in the next spot it might be.

Find The DataSource And Field Name

Generally speaking, it is a best practice to put code on the DataSource field instead on the form control. The reason for this is that code put on a form control will only affect that form control. Whereas, code on the DataSource field will affect any form control that uses that field. And it is fairly common to have the same field shown on more than one place on a form.

In order to find the DataSource field, we need to know the name of the DataSource and field used by that form control. Fortunately, the ‘form information’ dialog from the browser provided this information.

That said, if you forgot to write that information down, there is another way to see this information from within Visual Studio. First, right click on the form control and select ‘Properties‘. Then, locate the ‘Data Field‘ and ‘Data Source‘ property values in the Properties window.

Next, in order to see all of the nodes in the form designer, clear out the value in the form designer search and click ‘Enter‘.

Find The Method On The DataSource Field

Now that you know the name of the Datasource, PurchTable, and the name of the field, OneTimeVendor, locate them in the form designer.

First, expand Data Sources>PurchTable>Fields in the left pane of the form designer window.

Second, locate the OnteTimeVendor field, and expand its node and the Methods node underneath.

Hooray, there is a method named ‘modified’ found here.

Third, double click on the method to open it in a code editor window.

Attach The Debugger

Finally, we have found the code that runs first when changing the ‘one-time vendor’ radio button. The next step in this D365 debug tutorial is to step through the code to find where the error message is being thrown.

As you can see, this process is WAY longer than using the ‘Find Labels’ technique. However, I still wanted to show it to you so you can appreciate the difference. And, because there will be many times when you cannot use the ‘Find Labels’ technique.

First, add a breakpoint to the first line of code in the method by either pushing the F9 key on your keyboard, or clicking on the vertical bar just to the left of the code. If you did it right, a red circle will appear on the vertical bar.

Second, attach the debugger by going to Debug>Attach to Process… in Visual Studio.

In the form that opens, select the ‘iisexpress.exe‘ Process from the grid. Then, click the ‘Attach‘ button.

Importantly, Visual Studio will take some time to load the debug symbols. Ensure, that the breakpoint you added goes back to a fully filled in red circle. If it stays showing as a red outline circle, then the symbols did not load. If this happens to you, see my article on How To Load D365 Debug Symbols to correct this.

Debug The Code

Now that the debugger is attached, we can finally use the debugger to help us see when the system stops running code, when the error message is thrown.

First, repeat the replication steps. Immediately after clicking the ‘One-time vendor’ radio button, Visual Studio should hit the breakpoint.

Second, use the ‘Step Into F11’ and ‘Step Over F10’ keys to tell the system to move to the next line of code.

Specifically, push F10, to move to the ‘If’ statement on line 738.

Next, push F11 to step into the ‘VendTablecreateOneTimeAccountValidate()’ method.

Third, push F10 five more times, until the system is on the ‘checkFailed(“@SYS57595”);‘ line of code.

Next, hover over the label @SYS57595. Notice, Visual Studio will convert the label into text. Confirm that this is the error message you are experiencing in the internet browser.

Yay! You found the code that shows the error message. As a reminder, you found the code that runs first in your replication steps. Then, debugged the code until you encountered the code with the error message.

Determine The Conditions

After completing step one, find the code, next you need to determine the conditions that cause the error message to show.

Understand The IF Statement

Specifically, there is an ‘If’ statement that surrounds the error message.

First, the system calls ‘find()’ on the VendParameters table. It is important to know that parameter tables only ever store, and return, a single record. Therefore, there is no parameter passed into the ‘find’ method as criteria to find it.

Second, the system reads the ‘DefaultVend‘ field from that table.

Third, the system passes the value in the ‘DefaultVend‘ field to the ‘find‘ method of the VendTable table.

To see what this method does, put your cursor on the VendTable::find() method, then right click and select ‘Go to Definition‘.

Immediately, Visual Studio will open a code editor displaying the code in this method.

From here, notice that the first parameter of this method expects a vendor account. Further down, it uses this value in a ‘select statement‘ to find a VendTable record whose AccountNum field matches that value.

Finally, back in the calling method, notice there is an exclamation point in front of the code. This means ‘Not’.

Conclusions

Therefore, using all of this information we can determine the reason why the system is going into the ‘if’ statement and showing the error message. The VendTable ‘find‘ method is not returning a found record. This is either because the vendor account passed to it does not exist, or because the vendor account is blank.

To fix our issue, we need to see what value is stored in the VendParameters ‘DefaultVend‘ field. Then, ensure it is set to a value that can be found in the VendTable table.

Navigate To The Form Where Data Can Be Changed

In the last D365 debug tutorial, I walked through the steps of using ‘find all references’ to find the form where the table could be edited.

In this example, right click on VendParameters in the Application Explorer and select ‘Find all references‘. There will be 1092 results!

However, based on our understanding of best practices, we can look for a form named ‘VendParameters’, and we will find one.

Next, you can repeat the steps on the VendParameters form to find a Menu Item named ‘VendParameters‘. And then once more, to find a ‘Display Menu Item‘ named VendParameters. Or, you could make some assumptions, and look immediately for the Display Menu Item named ‘VendParameters‘.

After that, right click on the ‘VendParameters‘ Menu Item and select ‘Find all References‘.

From those results, you will see that the form can be found by navigating to AccountsPayable>Setup>VendParameters.

By looking at the labels on each of those nodes in the AccountsPayable Menu, the front end path is: Accounts Payable>Setup>Accounts payable parameters.

Find The Data On The Form That Needs To Change

We are almost there! Lastly, we need to find where in this form the field ‘DefaultVend’ is shown.

In the Application Explorer, search for the VendParameters table. Next, expand the fields node until you locate the ‘DefaultVend’ field. Then, right click on the field and select ‘Find All References’.

In the ‘Find Symbol Results’ window, click on the line ‘Form/VendParameters/FormDesign/FormDesign/FormStrongControl/Vendor_DefaultVend?DataField‘

Immediately, Visual Studio will open and select the form control in the Form Designer.

Next, you can see that the field is the FIRST field inside of the ‘General‘ tab, under a fast tab named ‘VendorTabPage‘, in a group named ‘Vendor‘. Most likely, you will be able to find the field on the front end using that information. Otherwise, you can look at the labels used on each of those form controls for the exact labels you will see on the front end.

To double check this, right click on the ‘One-time vendor account’ label and ensure the ‘control name’ matches what you found in Visual Studio.

Change The Data And Re-Test

Finally, we see that the issue is that the ‘One-time vendor account’ field on the ‘Accounts payable parameters’ form is blank. Whenever this field is blank, no corresponding vendor account record is found, which causes the error message to be thrown.

The error message did tell the user to go to the ‘vendor parameters’ form. However, the error message was not clear enough to understand which field needed to be looked at. Additionally, it did not help us understand that we need this field set.

To fix the issue, set the ‘One-time vendor account’ to a value of your choosing.

Importantly, after changing the value, click the ‘Save‘ button on the form.

Afterward, retry the replication steps, and ensure you no longer receive the error message when setting the ‘one-time vendor’ radio button.

Microsoft Documentation

For more information on debugging, see this Microsoft documentation.

I also want to thank my colleague Alyssa Lee for coming up with many of these example debugging situations. Thank you Alyssa.

Conclusion

In this D365 debug tutorial, you used the ‘Find Labels’ form to locate an error message in code. Additionally, you found the code that is run immediately after your last action, and debugged forward from there to find the same error message in code. After that, you practiced the remaining three steps of determining the condition that causes that error message, finding the form needed to change that condition, then changing the data and re-testing. Practicing these steps yourself is vital to improving. In future tutorials, I will continue to cover examples designed to teach you the techniques you need to know to solve complex issues.

Peter Ramer

Peter Ramer is a part of the Managed Application Services team at RSM working on Microsoft Dynamics 365. He focuses on the Retail and Commerce industries. When he is not solving problems and finding ways to accelerate his clients' business, he enjoys time with his three kids and amazing wife.