Debug Basics

Before getting into this D365 debug tutorial example, I want to 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.

As a quick reminder, you first add breakpoints to the D365 code using Visual Studio and the hotkey F9.

Second, in Visual Studio go to Debug>Attach To Process, then select ‘iisexpress.exe‘.

Third, perform your action in Dynamics 365 using an internet browser.

Fourth, if the system ran code where you have a breakpoint, Visual Studio should stop on that line of code. If your breakpoints looks like empty read circles, then please see my article on How To Load D365 Debug Symbols on steps to correct this.

Now that you know the basics of debugging, it is very important to learn how to use debugging to solve different kinds of problems.

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.

Set Up

In order to practice solving this D365 debug tutorial, you first need to run a Runnable Class (Job) to set up the data for this practice problem.

First, this lab assumes you are using a D365 environment with ‘demo data’. When deploying a D365 azure cloud hosted development environment, specify that you wish to create it with ‘demo data’ for practicing this example.

Second, create a D365 Project in Visual Studio.

Third, set the model of the project to your own custom model. If you have not done so already, follow these instructions to Create a Model in D365.

Fourth, right click on the project, and select ‘Add New Item‘. Select ‘Runnable Class (Job)‘, enter a name, such as ‘TutorialDebugAndSolve‘, then click ‘Add‘.

Fifth, copy in the following code. The complete class should look like this:

internal final class TutorialDebugAndSolve
{
    public static void main(Args _args)
    {
        //Tutorial 1
        changecompany('USP2')
        {
            CustParameters custParameters = CustParameters::findByCompany('USP2');

            ttsbegin;
            custParameters.selectforupdate(true);
            custParameters.MandatoryTaxGroup = NoYes::Yes;
            custParameters.update();
            ttscommit;

            info("Tutorial 1 set up complete.");
        }
    }
}

In this case, it is actually best if you do not look at the code. This code is just here to set up the mystery that you will solve as part of this lesson.

Sixth, right click on the Runnable Job in the Solution Explorer, and select ‘Set as Startup Object‘.

Finally, click the ‘Start’ button in the top bar of Visual Studio. Visual Studio will compile the code, and run it. Again, this is simply to set up the problem.

Practice Problem #1

In this first D365 debug tutorial, pretend a D365 user comes to you who is trying to set up a new customer, but the keep receiving an error. The error message reads “Tax group for customer must be specified.”

They could fill in the ‘sales tax group’ field. However, in their business they don’t use tax groups. Can you help allow a customer be created without this field populated?

Replication Procedures

Before investigating this D365 debug tutorial problem, we need to first confirm we can replicate the issue.

First, open D365 in a browser, and change the company, also known as a legal entity, to ‘USP2’.

Second, navigate to Accounts Receivable>All customers.

Third, after the form opens, click the ‘New‘ button on the form.

Fourth, fill in values for the fields Customer account, Name, and Customer Group. Then click ‘Save’.

You should see the warning message: “Tax group for customer must be specified”.

Try To Solve The Problem

Now that you have replicated the issue in this D365 debug tutorial, please try to solve the problem on your own.

Specifically, to solve a problem, we most often need to determine four things.

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 the next section, I will share one approach for finding the warning message. Over several examples, you will learn several different approaches. After that, I will share the answer of what data needs to be changed and where to change it.

Find The Code: Find Labels

As I said, there are multiple great approaches to finding the code that is causes an error message. In this D365 debug tutorial, learn how to find the label of the message being shown. Then, find where that label is used in code.

A label is an ID such as @SYS113299 which corresponds to some text that is stored in a label file. The quick explanation is that this allows a text to be stored in several different languages, such as English, Spanish, French, ect. The code tells the system to display whatever text is associated with label ID @SYS113299 in the user’s language. More on that in a separate article.

For now, 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 “Tax group for customer must be specified.” Then hit ‘Enter‘ on your keyboard.

Notice, the system will search the label files and return back any results. In this case, this message appears in one label file. We can see that the label ID is @SYS113299.

Typically, this form is used by editing the text related to a label. However, it can also be used to find labels, and the code that references that label ID.

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

Find References

Once the ‘Find References‘ option is selected, a window in Visual Studio shows all places in code that is text is found. Interestingly, the option can also be used on methods, and Application Explorer options.

In this case, there is only one result. First, click ‘Cancel‘ on the ‘Label Search‘ window. Then, double click on the one line in the Find Symbol Results window.

Notice, Visual Studio will open this location ‘Tables/CustTable/Methods/validateWrite’ in a code editor window. Additionally, the cursor will be placed on the line of code that references this label.

Congratulations, you have found the code where this message comes from.

Determine The Conditions

Now that you have found the place in code, the next step in this D365 debug tutorial is to determine the reason the message is being shown. In most cases, there is some ‘if’ statement around the code, that when the conditions are met, causes the message to be shown.

Specifically, we can see that the system checks two conditions.

First, the system checks to see if the ‘MandatoryTaxGroup‘ field on the CustParameters table is true
Second, it checks to see if the TaxGroup field on this CustTable (customer) table is set to blank.

In this example, we want the TaxGroup to be left blank, because the D365 user’s business does not need a tax group on the customers. Therefore, it is the first check we need to focus on.

By reading the code we can determine that if we can make the ‘MandatoryTaxGroup field on the CustParameters table to be set to false, then, the system will not show the message, and will continue on, hopefully allowing the customer to be saved.

Find The Form To Change The Data

To recap, we know we need to set the MandatoryTaxGroup field to false on the CustParameters table. However, where do we navigate in D365 to do that?

Often times, tables have a main form that allows data in that table to be modified. If we can determine the name of the form, then the menu item that calls that form, and the place in the Menu that the Menu item is called form, we will have our answer.

Find The Menu Path To The Form

First, type in ‘CustParameters‘ in the Application Explorer in Visual Studio. Then, hit ‘Enter‘.

Second, locate the ‘CustParameters‘ table under the ‘Data Model>Tables‘ node. Then, right click and select ‘Find All References’ from the menu.

Third, in the ‘Find Symbol Results’ window, look for a ‘Form’, that has this table as a data source. Very often, the form will be named the same as the table. And you can just search for the form direclty.

In this case, I see there is a form named ‘CustParameters‘, with a FormDataSourceRoot of ‘CustParameters‘ in the Find All References results.

Fourth, now that we know the name of the form that will allow us to modify this data, locate the form named ‘CustParameters‘ in the Application Explorer.

We need to know the name of the Menu Item that opens this form. Again, right click and select ‘Find All References’ on the form.

Fifth, scroll down in the ‘Find Symbol Results’ and look for a Menu Item that calls this form. In this example there is a Menu Item named ‘CustParameters‘. Tip: Often times the table, form and menu item are named the same thing. Therefore, you can just look for the Menu Item from the start. But if you don’t find it, follow this process.

Finally, repeat the process once more, to determine where in a Menu the Menu Item exists.

Hooray, we see the menu path to the form that contains the data we need to modify is located in the ‘Accounts Receivable‘ module, under the sub menu ‘Setup‘, and is first one in the list. By looking at the label on the menu item, we can see it will show in the browser as ‘Accounts receivable parameters’.

Find The Field On The Form

In order to find the field on the form, there are two approaches.

First, open the table ‘CustParameters‘, in the Application Explorer. Then, expand the ‘Fields’ node, and locate the ‘MandatoryTaxGroup‘ field. Next, right click the field and select ‘Find all References‘. In the Find Symbol Results window, locate the result that shows which form control on the ‘CustParameters‘ form is using that field. Click on it to see where on the form, the field is located.

In this example, I can see that the field is in the ‘General‘ fast tab, in a group named ‘Customer‘.

For the second approach, open the ‘CustParameters‘ form designer. Then, type ‘MandatoryTaxGroup‘ in the top search form. This approach does not always work. But if the form control is named after the field, you will find the form control. From there, you can see where in the form the form control is located.

The Answer

Finally, to solve this D365 debug tutorial, navigate to the form Accounts Receivable>Setup>Accounts receivable parameters.

Next, locate the ‘Mandatory tax group’ field in the ‘General’ tab. Toggle the field to false (or off). Then, push the ‘Save‘ button.

Lastly, repeat the Replication Procedures above and confirm the user is now able to save the new customer.

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

Importantly, there are more than one way to solve a problem. If you have seen an error message before you may remember what to do to resolve it. Or the error message may be clear enough to take action. Otherwise, using the ‘Find Labels’ form is a great way to find the code which will help you to understand the root cause. In this lesson, we did not even have to debug. We were able to use ‘Find labels‘ and ‘Find All References‘ to locate the code and understand the problem.

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.

D365 Debug Tutorial #1