As the name implies, the AOT is a tree view. The root of the AOT contains the element categories, such as Classes, Tables, and Forms. Some elements are grouped into subcategories to provide a better structure. For example, Tables, Maps, Views, and Extended Data Types are located under Data Dictionary, and all web-related elements are located under Web. Figure 2-2 shows the AOT.

You can navigate through the AOT by using the arrow keys on the keyboard. Pressing the right arrow key expands a node if it has any children.

Elements are arranged alphabetically. Because thousands of elements exist, understanding the naming conventions and adhering to them is important to use the AOT effectively.

All element names in the AOT use the following structure:

<Business area name> + <Functional area> + <Functionality, action performed, or type of content>

With this naming convention, similar elements are placed next to each other. The business area name is also often referred to as the prefix. Prefixes are commonly used to indicate the team responsible for an element. For example, in the name VendPaymReconciliationImport, the prefix Vend is an abbreviation of the business area name (Vendor), PaymReconciliation describes the functional area (payment reconciliation), and Import lists the action performed (import). The name CustPaymReconciliationImport describes a similar functional area and action for the business area Customer.

Figure 2-2. The AOT.

Table 2-2 contains a list of the most common prefixes and their descriptions.

Projects, described in detail later in this chapter, provides an alternative view of the information in the AOT.

You can create new elements in the AOT by right-clicking the element category node and selecting New <Element Type>, as shown in Figure 2-3.

Elements are given automatically generated names when they are created. However, you should replace the default names with new names that conform to the naming convention.

Each node in the AOT has a set of properties and either subnodes or X++ code. You can use the property sheet (shown in Figure 2-9) to inspect or modify properties, and you can use the X++ code editor (shown in Figure 2-11) to inspect or modify X++ code.

Figure 2-3. Creating a new element in the AOT.

The order of the subnodes can play a role in the semantics of the element. For example, the tabs on a form appear in the order in which they are listed in the AOT. You can change the order of nodes by selecting a node and pressing the Alt key while pressing the Up or Down arrow key.

A red vertical line next to a root element name marks it as modified and unsaved, or dirty, as shown in Figure 2-4.

Figure 2-4. A dirty element in the AOT, indicated by a vertical line next to the top-level node AccountingDistribution.

A dirty element is saved in the following situations:

If several developers modify elements simultaneously in the same installation of Microsoft Dynamics AX, each developer’s local elements might not be synchronized with the latest version. To ensure that the local versions of remotely changed elements are updated, an autorefresh thread runs in the background. This autorefresh functionality eventually updates all changes, but you might want to force a refresh explicitly. You do this by right-clicking the element you want to restore and then click Restore. This action refreshes both the on-disk and the in-memory versions of the element.

Typically, the general integrity of what’s shown in the AOT is managed automatically, but some operations, such as restoring the application database or reinstalling the application, can lead to inconsistencies that require manual resolution to ensure that the latest elements are used, as follows:

Each node in the AOT contains a set of available actions. You can access these actions from the context menu, which you can open by right-clicking any node.

Here are two facts to remember about actions:

A frequently used action is Open New Window, which is available for all nodes. It opens a new AOT window with the current node as the root. This action was used to create the screen capture of the AccountingDistribution element shown in Figure 2-4. After you open a new AOT window, you can drag elements into the nodes, saving time and effort when you’re developing an application.

You can extend the list of available actions on the context menu. You can create custom actions for any element in the AOT by using the features provided by MorphX. In fact, all actions listed on the Add-Ins submenu are implemented in MorphX by using X++ and the MorphX tools.

You can enlist a class as a new add-in by following this procedure:

When you modify an element from a lower layer, a copy of the element is placed in the current layer and the current model. All elements in the current layer appear in bold type (as shown in Figure 2-5), which makes it easy to recognize changes. For a description of the layer technology, see the Layers section in Chapter 21.

Figure 2-5. An element in the AOT that exists in several layers.

You can use the Application object layer and Application object model settings in the Options form to personalize the information shown after the element name in the AOT (see Figure 2-1). Figure 2-5 shows a class with the option set to Show All Layers. As you can see, each method is suffixed with information about the layers in which it is defined, such as SYS, VAR, and USR. If an element exists in several layers, you can right-click it and then click Layers to access its versions from lower layers. It is highly recommended that you use the Show All Layers setting during code upgrade because it provides a visual representation of the layer dimension directly in the AOT.

You open projects from the AOT by clicking the Project icon on the toolbar. Figure 2-6 shows the Projects window and its Private and Shared projects nodes.

Figure 2-6. The Projects window, showing the list of shared projects.

Except for its structure, a project generally behaves like the AOT. Every element in a project is also present in the AOT.

When you create a new project, you must decide whether it should be private or shared among all developers. You can’t set access requirements on shared projects. You can make a shared project private (and a private project shared) by dragging it from the shared category into the private category.

You can specify a startup project in the Options form. If specified, the chosen project automatically opens when Microsoft Dynamics AX is started.

Projects can be automatically generated in several ways—from using group masks to customizing project types—to make working with them easier. The following sections outline the various ways to generate projects automatically.

Group masks

Groups are folders in a project. When you create a group, you can have its contents be automatically generated by setting the ProjectGroupType property (All is an option) and providing a regular expression as the value of the GroupMask property. The contents of the group are created automatically and are kept up to date as elements are created, deleted, and renamed. Using group masks ensures that your project is always current, even when elements are created directly in the AOT.

Figure 2-7 shows the ProjectGroupType property set to Classes and the GroupMask property set to ReleaseUpdate on a project group. All classes with names containing ReleaseUpdate (the prefix for data upgrade scripts) will be included in the project group.

Figure 2-7. Property sheet specifying settings for ProjectGroupType and GroupMask.

Figure 2-8 shows the resulting project when the settings from Figure 2-7 are used.

Filters

You can also generate a project based on a filter. Because all elements in the AOT persist in a database format, you can use a query to filter elements and have the results presented in a project. You create a project filter by clicking the Filter button on the project’s toolbar. Depending on the complexity of the query, a project can be generated instantly, or it might take several minutes.

With filters, you can create projects containing elements that meet the following criteria:

• Elements created or modified within the last month

• Elements created or modified by a named user

• Elements from a particular layer

Figure 2-8. Project created by using a group mask.

When you create a new project, you can specify a project type. So far, this chapter has discussed standard projects. The Test project, used to group a set of classes for unit testing, is another specialized project type provided in Microsoft Dynamics AX.

You can create a custom specialized project by creating a new class that extends the ProjectNode class. With a specialized project, you can control the structure, icons, and actions available to the project.

Navigation and editing in the X++ code editor use standard shortcuts, as described in Table 2-3. For Microsoft Dynamics AX 2012, some shortcuts differ from those in earlier versions to align with commonly used integrated development environments (IDEs) such as Microsoft Visual Studio.

The X++ code editor contains a set of editor scripts that you can invoke by clicking the Script icon on the X++ code editor toolbar or by typing <name of script>+TAB directly in the editor. Built-in editor scripts provide functionality such as the following:

The list of editor scripts is extendable. You can create your own scripts by adding new methods to the EditorScripts class.

You use the Label editor to create new labels. You can start the Label editor by using any of the following procedures:

You can use the Label editor (shown in Figure 2-14) to find existing labels. Reusing a label is sometimes preferable to creating a new one. You can create a new label by pressing Ctrl+N or by clicking New.

Figure 2-14. The Label editor.

In addition to finding and creating new labels, you can also use the Label editor to find out where a label is used. The Label editor also logs any changes to each label.

Consider the following tips when creating and reusing labels:

In the MorphX design environment, labels are referenced in the format @<LabelFileIdentifier><LabelID>. If you don’t want a label reference to be converted automatically to the label text, you can use the literalStr function. When a placeholder is needed to display the value of a variable, you can use the strFmt function and a string containing %n, where n is greater than or equal to 1. Placeholders can also be used within labels. The following code shows a few examples:

// prints: Time transactions
print "@SYS1";

// prints: @SYS1
print literalStr("@SYS1");

// prints: Microsoft Dynamics is a Microsoft brand
print strFmt("%1 is a %2 brand", "Microsoft Dynamics", "Microsoft");
pause;

The following are some best practices to consider when referencing labels from X++:

Using single and double quotation marks to differentiate between system text and user interface text allows the Best Practices tool to find and report any hard-coded user interface text. The Best Practices tool is described in depth later in this chapter.

The Best Practices tool includes about 400 rules, a small subset of the best practices mentioned in the SDK. You can define the best practice rules that you want to run in the Best practice parameters dialog box: on the Tools menu, click > Options > Development, and then click Best Practices.

The best practice rules are divided into categories. By default, all categories are turned on, as shown in Figure 2-16.

The best practice rules are divided into three levels of severity:

Figure 2-16. The Best Practice Parameters dialog box.

The Best Practices tool allows you to suppress errors and warnings. A suppressed best practice deviation is reported as information. This gives you a way to identify the deviation as reviewed and accepted. To identify a suppressed error or warning, place a line containing the following text just before the deviation:

//BP Deviation Documented

Only a small subset of the best practice rules can be suppressed. Use the following guidelines for selecting which rules to suppress:

After you set up the best practices, the compiler automatically runs the best practices check whenever an element is compiled. The results are displayed on the Best Practices list in the Compiler output dialog box.

Some of the metadata best practice violations can also be suppressed, but the process of suppressing them is different. Instead of adding a comment to the source code, the violation is added to a global list of ignored violations. This list is maintained in the macro named SysBPCheckIgnore. This allows for central review of the number of suppressions, which should be kept to a minimum.

You can use the Best Practices tool to create your own set of rules. The classes used to check for rules are named SysBPCheck<Element type>. You call the init, check, and dispose methods once for each node in the AOT for the element being compiled.

One of the most interesting classes is SysBPCheckMemberFunction, which is called for each piece of X++ code whether it is a class method, form method, macro, or other method. For example, if developers don’t want to include their names in the source code, you can implement a best practice check by creating the following method on the SysBPCheckMemberFunction class:

protected void checkUseOfNames()
{
    #Define.MyErrorCode(50000)
    container devNames = ['Arthur', 'Lars', 'Michael'];
    int i;
    int j,k;
    int pos;
    str line;
    int lineLen;

    for (i=scanner.lines(); i>0; i--)
    {
        line = scanner.sourceLine(i);
        lineLen = strLen(line);
        for (j=conLen(devNames); j>0; j--)
        {
            pos = strScan(line, conPeek(devNames, j), 1, lineLen);
            if (pos)
            {
                sysBPCheck.addError(#MyErrorCode, i, pos,
                    "Don't use your name!");
            }
        }
    }
}

To enlist the rule, make sure to call the preceding method from the check method. Compiling this sample code results in the best practice errors shown in Table 2-5.

In an actual implementation, names of developers would probably be read from a file. Ensure that you cache the names to prevent the compiler from going to the disk to read the names for each method being compiled.

For the debugger to start, a breakpoint must be hit when X++ code is executed. You set breakpoints by using the X++ code editor in the Microsoft Dynamics AX Development Workspace. The debugger starts automatically when any component hits a breakpoint.

You must enable debugging for each component as follows:

Ensure that you are a member of the local Windows Security Group named Microsoft Dynamics AX Debugging Users. This is normally ensured using setup, but if you did not set up Microsoft Dynamics AX by using your current account, you need to do this manually through Edit Local Users And Groups in the Windows Control Panel. This is necessary to prohibit unauthorized debugging, which could expose sensitive data, provide a security risk, or impose unplanned service disruptions.

To set or remove breakpoints, press F9. You can set a breakpoint on any line you want. If you set a breakpoint on a line without an X++ statement, however, the breakpoint will be triggered on the next X++ statement in the method. A breakpoint on the last brace will never be hit.

To enable or disable a breakpoint, press Ctrl+F9. For a list of all breakpoints, press Shift+F9.

Breakpoints are persisted in the SysBreakpoints and SysBreakpointLists database tables. Each developer has his or her own set of breakpoints. This means that your breakpoints are not cleared when you close Microsoft Dynamics AX and that other Microsoft Dynamics AX components can access them and break where you want them to.

The main window in the debugger initially shows the point in the code where a breakpoint was hit. You can control execution one step at a time while inspecting variables and other aspects of the code. Figure 2-17 shows the debugger opened to a breakpoint with all the windows enabled.

Figure 2-17. Debugger with all windows enabled.

Table 2-6 describes the debugger’s various windows and some of its other features.

Table 2-7 lists the most important shortcut keys available in the debugger.

When generating a UML data model, the Reverse Engineering tool looks for tables in the project. The UML model contains a class for each table and view in the project and its attributes and associations. Figure 2-19 shows a class diagram with the CustTable (customers), InventTable (inventory items), SalesTable (sales order header), and SalesLine (sales order line) tables. To simplify the diagram, some attributes have been removed.

The UML model also contains referenced tables and all extended data types, base enumerations, and X++ data types. You can include these items in your diagrams without having to run the Reverse Engineering tool again.

Fields in Microsoft Dynamics AX are generated as UML attributes. All attributes are marked as public to reflect the nature of fields in Microsoft Dynamics AX. Each attribute also shows the type. The primary key field is underlined. If a field is a part of one or more indexes, the field name is prefixed with the names of the indexes; if the index is unique, the index name is noted in brackets.

Relationships in Microsoft Dynamics AX are generated as UML associations. The Aggregation property of the association is set based on two conditions in metadata:

Figure 2-19. UML data model diagram.

The name of an association endpoint is the name of the Microsoft Dynamics AX relationship. The names and types of all fields in the relationship appear in brackets.

When generating an object model, the Reverse Engineering tool looks for Microsoft Dynamics AX classes, tables, and interfaces in the project. The UML model contains a class for each Microsoft Dynamics AX table and class in the project and an interface for each Microsoft Dynamics AX interface in the project. The UML model also contains attributes and operations, including return types, parameters, and the types of the parameters. Figure 2-20 shows an object model of the most important RunBase and Batch classes and interfaces in Microsoft Dynamics AX. To simplify the view, some attributes and operations have been removed and operation parameters are suppressed.

The UML model also contains referenced classes, tables, and all extended data types, base enumerations, and X++ data types. You can include these elements in your diagrams without having to run the Reverse Engineering tool again.

Fields and member variables in Microsoft Dynamics AX are generated as UML attributes. All fields are generated as public attributes, whereas member variables are generated as protected attributes. Each attribute also shows the type. Methods are generated as UML operations, including return type, parameters, and the types of the parameters.

The Reverse Engineering tool also picks up any generalizations (classes extending other classes), realizations (classes implementing interfaces), and associations (classes using each other). The associations are limited to references in member variables.

Figure 2-20. UML object model diagram.

When generating an entity relationship data model, the Reverse Engineering tool looks for tables and views in the project. The entity relationship model contains an entity type for each AOT table in the project and attributes for the fields in each table. Figure 2-21 shows an Entity Relationship Diagram (ERD) for the tables HcmBenefit (Benefit), HcmBenefitOption (Benefit option), HcmBenefitType (Benefit type,) and HcmBenefitPlan (Benefit plan).

Figure 2-21. ERD using IDEF1X notation.

Fields in Microsoft Dynamics AX are generated as entity relationship columns. Columns can be foreign key (FK), alternate key (AK), inversion entry (IE), and optional (O). A foreign key column is used to identify a record in another table, an alternate key uniquely identifies a record in the current table, an inversion entry identifies zero or more records in the current table (these are typical of the fields in nonunique indexes), and optional columns don’t require a value.

Relationships in Microsoft Dynamics AX are generated as entity relationships. The EntityRelationshipRole property of the relationship in Microsoft Dynamics AX is used as the foreign key role name of the relation in the entity relationship data model.

To open the Compare tool, right-click an element, and then click Compare. A dialog box opens where you can select the versions of the element you want to compare, as shown in Figure 2-26.

Figure 2-26. The Comparison dialog box.

The versions to choose from come from many sources. The following is a list of all possible types of versions:

Figure 2-27. How the upgraded version proposal is created.

Figure 2-28 shows the Advanced tab, on which you can specify comparison options.

Figure 2-28. Comparison options on the Advanced tab.

The following list describes the comparison options shown in Figure 2-28:

After you choose elements and set parameters, start the comparison by clicking Compare. Results are displayed in a three-pane dialog box, as shown in Figure 2-29. The top pane contains the elements and options that you selected, the left pane displays a tree structure resembling the AOT, and the right pane shows details that correspond to the item selected in the tree.

Color-coded icons in the tree structure indicate how each node has changed. A red or blue check mark indicates that the node exists only in a particular version. Red corresponds to the SYS layer, and blue corresponds to the old SYS layer. A gray check mark indicates that the nodes are identical but one or more subnodes are different. A not-equal-to symbol (≠) on a red and blue background indicates that the nodes are different in the two versions.

Figure 2-29. Comparison results.

Details about the differences are shown in the right pane. Color coding is also used in this pane to highlight differences the same way that it is in the tree structure. If an element is editable, small action icons appear. These icons allow you to make changes to code, metadata, and nodes, which can save you time when performing an upgrade. A right or left arrow removes or adds the difference, and a bent arrow moves the difference to another position. These arrows always come in pairs, so you can see where the difference is moved to and from. If a version control system is in use, an element is editable if it is from the current layer and is checked out.

Although Microsoft Dynamics AX provides the comparison functionality for development purposes only, the comparison functionality can be reused for other tasks. You can use the available APIs to compare and present differences in the tree structure or text representation of any type of entity.

The Tutorial_CompareContextProvider class shows how simple it is to compare business data by using these APIs and present it by using the Compare tool. The tutorial consists of two parts:

Figure 2-30 shows a comparison of two customers, the result of running the tutorial.

Figure 2-30. The result of comparing two customers using the Compare API.

You can also use the line-by-line comparison functionality directly in X++. The static run method on the SysCompareText class, shown in the following code, takes two strings as parameters and returns a container that highlights differences in the two strings. You can also use a set of optional parameters to control the comparison.

public static container run(str _t1,
      str _t2,
      boolean _caseSensitive = false,
      boolean _suppressWhiteSpace = true,
      boolean _lineNumbers  = false,
      boolean _singleLine  = false,
       boolean _alternateLines = false)

Figure 2-33 shows the element life cycle in a version control system. When an element is in a state marked with a lighter shade, it can be edited; otherwise, it is read-only.

You can create an element in two ways:

After you create an element, you must add it to the version control system. First, give it a proper name in accordance with naming conventions, and then click Add To Version Control on the context menu. After you create the element, you must check it in.

Figure 2-33. Element life cycle.

An element that is checked in can be renamed. Renaming an element deletes the element with the old name and adds an element with the new name.

Table 2-9 describes some of the tasks that are typically performed with a version control system. Later sections describe additional tasks that you can perform when using version control with Microsoft Dynamics AX.

Working with labels is similar to working with elements. To change, delete, or add a label, you must check out the label file containing the label. You can check out the label file from the Label editor dialog box.

The main difference between checking out elements and checking out label files is that simultaneous checkouts are allowed for label files. This means that others can change labels while you have a label file checked out.

Figure 2-34 shows the Check In dialog box.

Figure 2-34. The Check In dialog box.

If you create a new label when using version control, a temporary label ID is assigned (for example, @$AA0007 as opposed to @USR1921). When you check in a label file, your changes are automatically merged into the latest version of the file and the temporary label IDs are updated. All references in the code are automatically updated to the newly assigned label IDs. Temporary IDs eliminate the need for a central Team Server, which was required for Microsoft Dynamics AX 2009, because IDs no longer have to be assigned when the labels are created. If you modify or delete a label that another person has also modified or deleted, your conflicting changes are abandoned. Such lost changes are shown in the Infolog after the check-in completes.

Synchronization makes it possible for you to get the latest version of all elements. This step is required before you can check in any elements. You can initiate synchronization from the Development Workspace. On the Version Control menu, point to Periodic > Synchronize.

Synchronization is divided into three operations that happen automatically in the following sequence:

Use synchronization to make sure your system is up to date. Synchronization won’t affect any new elements that you have created or any elements that you have checked out.

Figure 2-35 shows the Synchronization dialog box.

Figure 2-35. The Synchronization dialog box.

Selecting the Force check box gets the latest version of all files, even if they haven’t changed, and then imports every file.

When using VSS, you can also synchronize to a label defined in VSS. This way, you can easily synchronize to a specific build or version number.

Synchronization is not available with MorphX VCS.

The way that you keep track of versions on the client depends on your version control system. VSS requires that Microsoft Dynamics AX keep track of itself. When you synchronize the latest version, it is copied to the local repository folder from the version control system. Each file must be imported into Microsoft Dynamics AX to be reflected in the AOT. To minimize the risk of partial synchronization, a log entry is created for each file. When all files are copied locally, the log is processed, and the files are automatically imported into Microsoft Dynamics AX.

When synchronization fails, the import operation is usually the cause of the problem. Synchronization failure leaves your system in a partially synchronized state. To complete the synchronization, restart Microsoft Dynamics AX and restart the import. You use the synchronization log to restart the import, and you access it from the Development Workspace menu at Version Control > Inquiries > Synchronization log.

The Synchronization Log dialog box, shown in Figure 2-36, displays each batch of files, and you can restart the import operation by clicking Process. If the Completed check box is not selected, the import has failed and should be restarted.

The Synchronization log is not available with MorphX VCS.

Figure 2-36. The Synchronization Log dialog box.

One of the biggest advantages of version control is the ability to track changes to elements. Selecting History on an element’s context menu displays a list of all changes to an element, as shown in Figure 2-37.

Figure 2-37. Revision history of an element.

This dialog box shows the version number, the action performed, the time the action was performed, and who performed the action. You can also see the change number and the change description.

A set of buttons in the History dialog box allows further investigation of each version. Clicking Contents opens a form that shows other elements included in the same change. Clicking Compare opens the Compare dialog box, where you can do a line-by-line comparison of two versions of the element. The Open New Window button opens an AOT window that shows the selected version of the element, which is useful for investigating properties because you can use the standard MorphX toolbox. Clicking View File opens the .xpo file for the selected version in Notepad.

Comparison is the key to harvesting the benefits of a version control system. You can start a comparison from several places, including from the context menu of an element by pointing to Compare. Figure 2-38 shows the Comparison dialog box, where two revisions of the form CustTable are selected.

Figure 2-38. Comparing element revisions from version control.

The Compare dialog box contains a list of all checked-in versions, in addition to the element versions available in other layers installed.

When you’re working on a project, it’s easy to lose track of which elements you’ve opened for editing. The Pending Objects dialog box, shown in Figure 2-39, lists the elements that are currently checked out in the version control system. Notice the column containing the action performed on the element. Deleted elements are available only in this dialog box; they are no longer shown in the AOT.

Figure 2-39. Pending elements.

You can access the Pending Objects dialog box from the Development Workspace menu: Version Control > Pending Objects.

Because the version control system contains .xpo files and not a model file, a build process is required to generate the model file from the .xpo files. The following procedure provides a high-level overview of the build process:

The build process doesn’t apply to MorphX VCS.

The implementation of the version control system in Microsoft Dynamics AX is fully pluggable. This means that any version control system can be integrated with Microsoft Dynamics AX.

Integrating with another version control system requires a new class implementing the SysVersionControlFileBasedBackEnd interface. It is the implementation’s responsibility to provide the communication with the version control system server being used.