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 reside under Data Dictionary, and all Web-related elements are found under Web. Figure 3-2 shows the AOT.

Figure 3-2. Application Object Tree

You can navigate 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 ordered alphabetically. Because thousands of elements exist, understanding the naming conventions and adhering to them is important to effectively using the AOT.

All element names in the AOT follow this structure:

In 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.

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

Tip

When creating new elements, make sure to follow the recommended naming conventions. Any future development and maintenance will be much easier.

The Project Designer, described in detail later in this chapter, provides an alternative view of the information organized by the AOT.

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

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

Objects are given automatically generated names when they are created. However, you should replace the default names with new names in accordance with the naming conventions.

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 3-9) to inspect or modify properties, and you can use the X++ code editor (shown in Figure 3-11) to inspect or modify X++ code.

The order of the subnodes can play a role in the semantics of the element. For example, the tabs on a form display 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 an element name marks it as modified and unsaved, or dirty, as shown in Figure 3-4.

Figure 3-4. A dirty element in the AOT, indicated by a vertical line next to CustTable (sys)

A dirty element is saved in the following situations:

If several developers modify elements simultaneously in the same installation of Dynamics AX, each developer’s local elements could become out of sync 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 explicitly force a refresh. You do this by right-clicking the element you want to restore and then selecting Restore. This action refreshes both the on-disk and the in-memory versions of the element. The following is a less elegant way of ensuring that the latest elements are used:

Note

Before Dynamics AX 4.0, the application object cache was stored in .aoc files. To support Unicode, the file extension was changed to .auc in Dynamics AX 4.0.

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 the node in question.

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 nodes as the root. We used this action to create the screen capture of the CustTable element shown in Figure 3-4. Once 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. All elements in the current layer appear in bold type (as shown in Figure 3-5), which makes it easy to recognize changes. For a description of the layer technology, see the section "Application Model Layering System" in Chapter 1.

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

You can use the Application Object Layer setting in the Options dialog box to personalize the layer information shown in the AOT. Figure 3-5 shows a class with the option set to 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 select Layers to access its versions from lower layers. We highly recommend the All Layers setting during code upgrade because it provides a visual representation of the layer dimension directly in the AOT.

Note

If you modify an element that exists in a higher layer than your current layer, all modifications are redirected to the upper layer where the element is defined.

You open the Project Designer by clicking the Project button on the toolbar. Figure 3-6 shows the Project Designer and its Private and Shared projects.

Figure 3-6. Project Designer, showing available private and shared projects

Except for its structure, the Project Designer behaves exactly 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.

Note

Central features of Dynamics AX 2009 are captured in shared projects to provide an overview of all the elements in a feature. No private projects are included with the application.

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

Projects can be automatically generated in several ways—from using group masks to customizing special project types—to make working with them easier. We discuss the various ways to automatically generate projects in the sections that follow.

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 a regular expression as the GroupMask property. The contents of the group are created automatically and 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 3-7 shows the ProjectGroupType property set to Tables and the GroupMask property set to <xRef on a project group. All table names starting with xRef (the prefix for the Cross-reference tool) will be included in the project group.

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

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

Figure 3-8. Project created by using group masks

When you create a new project, you can specify a project type. So far in this chapter, we’ve limited our discussion to standard projects. Two specialized project types are also provided in Dynamics AX:

You can create a custom specialized project by creating a new class that extends the ProjectNode class. Specialized projects allow you to 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 3-3.

The X++ code editor contains a set of editor scripts that you can invoke by clicking the Script button on the X++ Code Editor toolbar or by pressing Alt+R. Editor scripts provide functionality such as the following:

Note

Code generation allows you to create, in a matter of minutes, a new class with the right constructor method and the right encapsulation of member variables by using parm methods. Parm methods (parm is short for "parameter") are used as simple property getters/setters on classes. Naturally, code generation is carried out in accordance with X++ best practices.

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 it using any of the following procedures:

The Label Editor (shown in Figure 3-13) allows you to find existing labels. Reusing a label is often preferable to creating a new one. You can create a new label by pressing Ctrl+N or by clicking the New button.

Figure 3-13. Label Editor

In addition to allowing you to find and create new labels, the Label Editor can also show where a label is used. It also logs any changes to each label.

The following are tips to consider 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 automatically convert 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> = 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");

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 designers can be helpful tools for learning how the IntelliMorph layout scheme works. If you have the Visual Form Designer open when you start designing a form, you immediately see what the form will look like, even when it is modified in the AOT. In fact, after creating a few forms, you’ll probably feel so confident of the power of IntelliMorph and the effectiveness of designing forms in the AOT that you’ll only rarely use the Visual Form Designer.

You open the Visual Form Designer by right-clicking a form’s design in the AOT and selecting Edit. The designer is shown in design mode in Figure 3-14. Next to the form is a toolbar with all the available controls, which can be dragged onto the form’s surface. You can also see the property sheet showing the selected control’s properties.

Figure 3-14. Visual Form Designer

One interesting form that overrides IntelliMorph is the form tutorial_Form_freeform. Figure 3-15 shows how a scanned bitmap of a payment form is used as a background image for the form, and the controls positioned where data entry is needed.

Figure 3-15. Nonstandard form that uses a bitmap background

The majority of MorphX reports fall into two categories—internal and external. Requirements for reports used internally in a company are often more relaxed than requirements for external reports. External reports are often part of the company’s face to the outside world. An invoice report is a classic example of an external report.

Leveraging the features of IntelliMorph, internal reports typically follow an autodesign that allows the consumer of the report to add and remove columns from the report and control its orientation, font, and font size.

External reports typically use a generated design, which effectively overrides IntelliMorph. So for external reports, the Visual Report Designer is clearly preferable. Often, external reports are printed on preprinted paper containing, for example, the company’s letterhead, so the ability to easily control the exact position of each control is essential.

You create a generated design from an autodesign by right-clicking a design node of a report in the AOT and selecting Generate Design. You can open the Visual Report Designer by right-clicking a generated design and selecting Edit. As shown in Figure 3-16, each control can be moved freely, and new controls can be added.

Figure 3-16. Visual Report Designer

Notice the zoom setting in the lower-right corner of Figure 3-16. This setting allows you to get a close-up view of the report and, with a steady hand, position each control exactly where you want it.

The rendering subsystem of the report engine can print only generated designs because it requires all controls to have fixed positions. If a report has only an autodesign, the report engine generates a design in memory before printing.

The Best Practices tool includes about 350 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: from the Microsoft Dynamics AX drop-down menu, click ToolsOptions and then the Best Practices button.

Note

You must set the compiler error level to 4 if you want best practice rule violations to be reported. To turn off the Best Practices tool, click ToolsOptionsCompiler, and then set the diagnostic level to less than 4.

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

Figure 3-18. Best Practice Parameters dialog box

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

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 tab in the Compiler Output dialog box.

The X++ Best Practices tool allows you to create your own set of rules. The classes used to check for rules are named SysBPCheck<ElementKind>. 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;
    int pos;
    str line;
    int lineLen;

    for (i=scanner.lines(); i; i--)
    {
        line = scanner.sourceLine(i);
        lineLen = strlen(line);
        for (j=conlen(devNames); j; 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 3-5.

In a real-world implementation, names of developers would probably be read from a file. Make sure to 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 during execution of X++ code. You set breakpoints by using the X++ code editor in the Microsoft Dynamics AX client. The debugger starts automatically when any component hits a breakpoint.

You must enable debugging for each component as follows:

Caution

We recommend that you do not enable any of the debugging capabilities in a live environment. If you do, execution will stop when it hits a breakpoint, and users will experience a hanging client.

The debugger allows you to set and remove breakpoints by pressing 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.

You can enable or disable a breakpoint by pressing Ctrl+F9. For a list of all breakpoints, press Shift+F9.

Breakpoints are persistent in the SysBreakpoints database table. Each developer has his or her own set of breakpoints. This means that your breakpoints are not cleared when you close Dynamics AX and that other 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 variables and other aspects are inspected. Figure 3-19 shows the debugger opened to a breakpoint with all the windows enabled.

Figure 3-19. Debugger with all windows enabled

In the following subsections, we briefly describe the debugger’s various windows and some of its other features.

Variables Window

In this window, local, global, and member variables are shown. Local variables are variables in scope at the current execution point. Global variables are the global classes that are always instantiated: Appl, Infolog, ClassFactory, and VersionControl. Member variables make sense only on classes, and they show the class member variables.

The Variables window shows the name, value, and type of each variable. If a variable is changed during execution stepping, it is marked in red. Each variable is shown associated with a client or server icon. You can modify the value of a variable by double-clicking the value.

Tip

As a developer, you might want to provide more information in the value field than what is provided by default. For a class, the defaults are New and Null. You can change the defaults by overriding the toString method. If your class doesn’t explicitly extend object (the base class of all classes), you must add a new method named toString, returning str and taking no parameters, to implement this functionality.

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 3-21 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.

Figure 3-21. UML data model diagram

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 Dynamics AX are generated as UML attributes. All attributes are marked as public because of the nature of fields in 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 names of the indexes are prefixed to the field name; if the index is unique, the index name is noted in brackets.

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

The end name on associations is the name of the Dynamics AX relationship, and the names and types of all fields in the relationship appear in brackets.

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

Figure 3-22. UML object model diagram

The UML model also contains referenced tables, classes and 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 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.

Note

To get the names of operation parameters, you must reverse engineer in debug mode. The names are read from metadata only and placed into the stack when in debug mode. You can enable debug mode on the Development tab in the Options dialog box by selecting When Breakpoint in the Debug Mode list.

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 each table’s fields. Figure 3-23 shows an Entity Relationship Diagram (ERD) 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.

Figure 3-23. ERD using IDEF1X notation

Fields in 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 Dynamics AX are generated as entity relationships. The EntityRelationshipRole property of the relationship in Dynamics AX is used as the foreign key role name of the relation in the entity relationship data model.

Note

The Reverse Engineering tool produces an ERX file. To work with the generated file in Visio, you must start Visio, create a new Database Model Diagram and select Database, and point to Import and then Import Erwin ERX file. Afterward you can drag relevant tables from the Tables And Views pane (available from the Database menu) to the diagram canvas.

You open the Compare tool by right-clicking an element and then clicking Compare on the Add-Ins submenu. A dialog box allows you to select the versions of the element you want to compare, as shown in Figure 3-28.

Figure 3-28. Comparison dialog box

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

Figure 3-29. How the upgraded version proposal is created

Note

You can also compare two different elements. To do this, select two elements in the AOT, right-click, point to Add-Ins, and then click Compare.

Figure 3-30 shows the Advanced tab, on which you can specify comparison options.

Figure 3-30. Comparison options on the Advanced tab

The comparison options shown in Figure 3-30 are described in the following list:

After you choose elements and set parameters, you can start the comparison by clicking Compare. Results are displayed in a three-pane dialog box, as shown in Figure 3-31. The top pane is the element selection, the left pane is a tree structure resembling the AOT, and the right pane shows details of the tree selection.

Figure 3-31. Comparison results

The 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 red or blue element. 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.

Note

Each node in the tree view has a context menu that provides access to the Add-Ins submenu and the Open New Window option. The Open New Window option provides an AOT view on any element, including old layer elements.

Details of the differences are shown in the right pane. Color coding is also used in this pane to highlight differences. If an element is editable, small action icons appear. These icons allow you to make changes to source, 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. An element is editable if it is from the current layer and checked out if a version control system is used.

Although Dynamics AX uses the comparison functionality for development purposes only, the general comparison functionality can be used more widely. The available APIs allow you 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 presents it by using the Compare tool. The tutorial consists of two parts:

Figure 3-32 shows a comparison of two customers, the result of running the tutorial.

Figure 3-32. 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)

Refer to the Microsoft Dynamics AX 2009 SDK for documentation of the classes.

Figure 3-35 shows the element life cycle in a version control system. When the element is in a state marked with green, it can be edited; otherwise it is read-only.

Figure 3-35. Element life cycle

You can create a new 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.

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.

To modify an element, you must check it out. Checking out an element locks it so that others can’t modify it while you’re working.

By clicking ToolsDevelopment ToolsVersion ControlPending Objects from the Microsoft Dynamics AX drop-down menu, you can see which elements you currently have checked out. The elements you’ve checked out (or that you’ve created and not yet checked in), appear in blue, rather than black, in the AOT.

If you decide that you don’t want to modify an element that you checked out, you can undo the check-out. This releases your lock on the element and imports the server version of the element to undo your changes.

When you have finalized your modifications, you must check in the elements for them to be part of the next build. When you click Check-In on the context menu, the dialog box shown in Figure 3-36 appears, displaying all the elements that you currently have checked out. The Check In dialog box shows all open elements by default; you can remove any elements not required in the check-in from the list by pressing Alt+F9.

Figure 3-36. Check In dialog box

We recommend the following procedure for checking in your work:

Before the version control system accepts a check-in, it might subject the elements to quality checks. You define what is accepted in a check-in when you set up the version control system. The following checks are supported:

When a check is enabled, it is carried out when you do a check-in. If the check fails, the check-in stops. You must address the issue and restart the check-in.

You can set the Source Code Titlecase Update tool, available on the Add-Ins submenu, to automatically execute before elements are checked in to ensure uniform casing in variable and parameter declarations and references. You can specify this parameter when setting up the version control system by selecting the Run Title Case Update check box.

When using version control, you create new elements just as you normally would in the MorphX environment without a version control system. These elements are not part of your check-in until you click Add To Version Control on the context menu.

You can also create all element types except those listed in System Settings (from the Microsoft Dynamics AX drop-down menu: ToolsDevelopment ToolsVersion ControlSetup System Settings). By default, jobs and private projects are not accepted.

New elements should follow Dynamics AX naming conventions. The best practice naming conventions are enforced by default, so you can’t check in elements with names such as aaaElement, Del_Element, element1, or element2. (The only Del elements allowed are those required for version upgrade purposes.) You can change naming requirements in System Settings.

An element must be in the checked-in state to be renamed. Because all references in .xpo files are strictly name based (not ID based), all references to renamed elements must be updated. For example, when you rename a table field, you must also update any form or report that uses that field. Most references in metadata in the AOT are ID based, thus not affected when an element is renamed; in most cases, it is enough to simply check out the form or report and include it in the check-in to update the .xpo file. You can leverage the cross-reference functionality to identify references. References in X++ code are name based. You can use the compiler to find affected references.

An element’s revision history is kept intact when elements are renamed. No tracking information in the version control system is lost because of a rename.

You delete an element as you normally would in Dynamics AX. The delete operation must be checked in before the deletion is visible to other users of the version control system. You can see pending deletions in the Pending Objects dialog box.

Working with labels is very 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 check-outs are allowed for label files. This means that others can change labels while you have a label file checked out.

When you check in a label file, your changes are automatically merged into the latest version of the file. If you modify or delete a label that another person has also modified or deleted, your changes are lost. Lost changes are shown in the Infolog.

The ID server guarantees that label IDs are unique; adding labels won’t generate conflicts.

If someone else has checked in a new version of an element, the Get Latest option on the context menu allows you to get the version of the element that was most recently checked in. This option isn’t available when you have the element checked out yourself.

Get Latest is not applicable to MorphX VCS.

Synchronization allows 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 Microsoft Dynamics AX drop-down menu: ToolsDevelopment ToolsVersion ControlPeriodicSynchronize.

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

You should 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 3-37 shows the Synchronization dialog box.

Figure 3-37. Synchronization dialog box

Selecting the Force check box gets the latest version of all files, whether or not they have changed, and then imports every file.

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

Synchronization is not applicable to MorphX VCS.

How you keep track of versions on the client depends on the version control system being used. Visual SourceSafe requires that 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 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 Dynamics AX.

When synchronization fails, the import operation is usually the cause of any problems. Synchronization failure leaves your system in a partially synchronized state. To complete the synchronization, you must restart Dynamics AX and restart the import. You use the synchronization log to restart the import, and you access it from the Microsoft Dynamics AX dropdown menu at ToolsDevelopment ToolsVersion ControlInquiriesSynchronization Log.

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

Figure 3-38. Synchronization Log dialog box

The Synchronization Log is not available in MorphX VCS.

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 3-39.

Figure 3-39. 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 revision 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, which allows you to 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 it allows you to 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 the Compare option on the Add-Ins submenu. Figure 3-40 shows the Comparison dialog box where two revisions of the form CustTable are selected.

Figure 3-40. Comparing element revisions from version control

The Compare dialog box contains a list of all checked-in versions, in addition to the layer element versions, when a version control system is used.

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 3-41, 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 3-41. Pending elements

You can access the Pending Objects dialog box from the Microsoft Dynamics AX drop-down menu: ToolsDevelopment ToolsVersion ControlPending Objects.

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

You must follow these steps for each layer you build. The steps are described in more detail in the Microsoft Dynamics AX 2009 SDK.

The build process doesn’t apply to MorphX VCS.

The implementation of the version control system in Dynamics AX is fully pluggable. This means that any version control system can be integrated with 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.

To implement a unit test case, you must create a new class that extends the SysTestCase class, which is part of the Unit Test framework. You should give the class the same name as the class it is testing, suffixed with Test. This is illustrated in the following example, where a unit test for the Stack class is declared.

class StackTest extends SysTestCase
{
}

If you were to run the unit test at this point, you would find that zero tests were run and zero tests failed.

This default naming convention tells the Unit Test framework which test class to collect code coverage data for. If the default test class name doesn’t suit your needs, you can override the testsElementName method. You can also override the testsElementType method to set the kind of element for which the framework collects code coverage data.

To create a useful test, you must add one or more test methods to the class. All test method names must start with test. The test methods must return void and take no parameters. In the following code, a test method is added to the StackTest class.

void testPushPop()
{
    //Create an instance of the class to test.
    Stack stack = new Stack();
    ;
    //Push 123 to the top of the stack.
    stack.push([123]);
    //Pop the value from the stack and assert that it is 123.
    this.assertEquals([123], stack.pop());
}

Within each test method, you should exercise the object you test and confirm that it behaves correctly. Running the unit test at this point tells you that one test was run and zero tests failed.

Your testing needs should be met by the assertion methods available on SysTestCase (which extends SysTestAssert), as shown in Table 3-8.

If an assertion fails, the test method fails. You can configure the framework to stop at first failure or continue with the next test method in the Unit Test Parameters dialog box: from the Microsoft Dynamics AX drop-down menu, point to Tools Development ToolsUnit Test Parameters. The following code adds a new failing test method.

//Test the qty method, which returns the quantity of values on the stack.
void testQty()
{
    //Create an instance of the class to test.
    Stack stack = new Stack();
    ;
    //Push 123 to the top of the stack.
    stack.push([123]);
    //Pop the value from the stack and assert that it is 0.
    this.assertEquals(0, stack.qty());
}

Running the unit test at this point shows that two tests were executed and one failed. The failing test appears in the Infolog. Clicking Edit opens the X++ code editor on the assert call that failed.

You might have noticed code redundancy in the test methods shown so far. In many cases, initialization code is required before the test method can run. Instead of duplicating this code in all test methods, you can refactor it into the setUp method. If teardown logic is required, you can place it in the tearDown method. When the framework runs a test method, it instantiates a new test case class, which is followed by calls to setUp and test methods, and finally a call to the tearDown method. This prevents in-memory data from one test method from affecting another test method. Test suites, which are covered in the next section, provide ways to isolate data persisted in the database between test cases and methods. The following code uses the setUp method to refactor the sample code.

class StackTest extends SysTestCase
{
    Stack stack;

    public void setUp()
    {;
        super();
        //Create an instance of the class to test.
        stack = new Stack();
    }
    void testPushPop()
    {;
        stack.push([123]);
        this.assertEquals([123], stack.pop());
    }
    ...
}

The Unit Test framework also supports testing of exceptions. If a method is expected to throw an exception, you can instruct the framework to expect an exception to be thrown. If you expect an exception and none is thrown, the framework reports the test case as failed. You inform the framework that an exception is expected by calling parmExceptionExpected ([boolean, str]). You can specify an exception text that must exactly match the text thrown with the exception, or the test case will fail. You shouldn’t write more asserts after the method call expected to throw an exception because execution should never get that far. The following code adds a test method that expects an exception message to be thrown.

void testFailingPop()
{;
    //Assert that an exception is expected.
    this.parmExceptionExpected(true, "Stack is empty!");

    //Call the method expected to throw an exception.
    stack.pop();
}

The sample test case now has three test methods. By following these steps, you can run the test case from MorphX:

If you wanted to run the test case programmatically, you could use a test runner class. To do this, you would typically place the following logic in your test class’s main method, which is invoked when you press F5 in the X++ code editor.

static void main(args _args)
{
    SysTestRunner runner = new SysTestRunner(classStr(StackTest));
    SysTestListenerXML listener =
        new SysTestListenerXML(@"c:	mpStackTest.xml");
    ;
    runner.getResult().addListener(listener);
    runner.run();
}

Notice that you also register a listener. If you didn’t register a listener, you wouldn’t know the result of the test. Listeners are described in the section "Test Listeners" later in this chapter.

Test suites serve two purposes:

Dynamics AX includes the following five test suites that provide different levels of isolation:

For each test case, you can override the createSuite method to select the appropriate suite for your test case. The following code shows how to use the company isolation test suite in the StackTest class.

public SysTestSuite createSuite()
{;
    return new SysTestSuiteCompanyIsolateClass(this);
}

We recommend that you use test projects to group your test cases into suites. You can, however, create your own class extending from SysTestSuite and programmatically add test cases and other test suites to it. You can run each test suite in one of the following ways:

The following code shows the entire StackTest test case. Notice the refactoring and the changes in testQty to make the test case succeed.

class StackTest extends SysTestCase
{
    Stack stack;

    public SysTestSuite createSuite()
    {;
        return new SysTestSuiteCompanyIsolateClass(this);
    }
    public void setUp()
    {;
        super();
        stack = new Stack();
    }
    void testPushPop()
    {;
        stack.push([123]);
        this.assertEquals([123], stack.pop());
    }
    void testQty()
    {;
        stack.push([100]);
        this.assertEquals(1, stack.qty());
        stack.push([200]);
        this.assertEquals(2, stack.qty());
        stack.clear();
        this.assertEquals(0, stack.qty());
    }
    void testFailingPop()
    {;
        //Assert that an exception is expected.
        this.parmExceptionExpected(true, "Stack is empty!");

        //Call the method expected to throw an exception.
        stack.pop();
    }
    static void main(args _args)
    {
        //This method illustrates how to run a test case programmatically.
        SysTestRunner runner = new SysTestRunner(classStr(StackTest));
        SysTestListenerXML listener =
           new SysTestListenerXML(@"c:	mpStackTest.xml");
        ;
        runner.getResult().addListener(listener);
        runner.run();
    }
}

The easiest way to group test cases is to use a test project. You can create a test project with the Project Designer in MorphX. The test project can contain groups of test case classes and references to other test projects. You create a new test project by selecting the project type Test Project when creating either a shared or private project. A test project can also contain references to other test projects, which allows the project to scale across many development teams. You create a reference by right-clicking the project root node and selecting New Reference To Test Project.

Figure 3-42 shows a test project that includes a group of common tests containing the test case example and references to two other test projects.

Figure 3-42. Test project containing references and a test case

Each test project has its own settings that are persisted with the project definition. This allows you to specify test project settings that follow the project, even through import and export, redeployment, and so on.

You can run a test project in several ways:

When you’re working with unit testing, you should open the Test toolbar. You access the Test toolbar, shown in Figure 3-43, from the Microsoft Dynamics AX drop-down menu: Tools Development ToolsUnit TestShow Toolbar.

Figure 3-43. Test toolbar

You can type the name of the test case, test suite, or test project you want to run, click Run to execute it, and then, to get information about the result, click Details to open the Test Jobs window. The Test Jobs window shows you the following information collected during the test execution:

Note

The database listener collects the information displayed in the Test Jobs window. This listener is automatically registered when you run a test via the toolbar.

The Unit Test framework can collect code coverage information during execution, including a percentage value that indicates how thoroughly you have tested the unit. It also allows you to focus your implementation of the test cases on the parts not covered by other test cases. In addition, the Test Jobs window offers a line-by-line view of the code lines visited. You can enable code coverage in the Unit Test Parameters dialog box: from the Microsoft Dynamics AX drop-down menu, point to ToolsDevelopment ToolsUnit TestParameters. However, because much more data is collected, enabling code coverage when executing unit tests dramatically affects performance during execution. Figure 3-44 shows an example of the code coverage recorded by the testFailingPop method from the preceding test case example.

Figure 3-44. Visualization of code coverage

The lines highlighted in gray (lines 1 through 5 and 15 through 16) are the lines visited during execution. The lines not shaded (lines 6 through 14) haven’t been visited.

The value of running a test case is dramatically increased if good reporting options exist. When running a test case or a suite of tests, you can enable one or more listeners. Each listener produces its unique output. Dynamics AX includes many listeners, allowing output to text files, XML files, the database, the Infolog, the Message window, the Print window, and the Progress bar. You can enable test listeners in the Unit Test Parameters dialog box.

Here is the XML generated by the XML listener when you run the StackTest unit test.

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<!-- Created by SysTestListenerXML -->
<test-results date="08-07-2008" time="10:51:34" success="false">
  <test-suite name="stacktest" time="52" success="true" coverage="61.54">
    <results>
      <test-case name="stacktest.testFailingPop" time="31" success="true" coverage="23.08" />
      <test-case name="stacktest.testPushPop" time="0" success="true" coverage="50.00" />
      <test-case name="stacktest.testQty" time="21" success="true" coverage="30.77" />
    </results>
  </test-suite>
</test-results>

Note

Listeners that generate a file write the file to the application log directory. The only way to change the file name and location is to manually register a listener, which we demonstrated in the StackTest code in Test Suites to Test Projects.

If you must create a new listener to output to a type of media not supported by default, you can do so by following these steps:

So far in this chapter we’ve described the classes in the Unit Test framework and explained how they interact. Figure 3-45 shows this information as a UML object model.

Figure 3-45. UML diagram of the Unit Test framework

The SysTestCase class implements quite a few interfaces. In fact, the Unit Test framework can use any class that implements the SysTestable interface as a test case. You can implement the other interfaces if you want more control. It’s far easier, however, to create test case classes that extend the SysTestCase base class. (For simplicity, Figure 3-45 doesn’t show the SysTestSuite derived classes or the SysTestListener derived classes.)