Chapter 2. The MorphX development environment and tools

In this chapter

Introduction

Application Object Tree

Projects

The property sheet

X++ code editor

Label editor

Compiler

Best Practices tool

Debugger

Reverse Engineering tool

Table Browser tool

Find tool

Compare tool

Cross-Reference tool

Version control

This chapter describes the most commonly used tools and offers some tips and tricks for working with them. You can find additional information and an overview of other MorphX tools in the MorphX Development Tools section of the AX 2012 software development kit (SDK) on the Microsoft Developer Network (MSDN).

Table 2-1 lists the MorphX tools and components.

You can access these development tools from the following places:

In the Development Workspace, on the Tools menu

On the context menus of elements in the AOT

You can personalize the behavior of many MorphX tools by clicking Options on the Tools menu. Figure 2-1 shows the Options form.

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 there are thousands of elements, it’s important to understand the naming conventions and adhere to them 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 Customer business area.

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

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

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.

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

A dirty element is saved in the following situations:

When the element is executed.

When the developer explicitly invokes the Save or Save All action.

When autosave takes place. You specify the frequency of autosave in the Options form, which is accessible from the Tools menu.

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. To perform manual resolution, follow these steps:

1. Close the AX 2012 client to clear any in-memory elements.

2. Stop the Microsoft Dynamics Server service on the Application Object Server (AOS) to clear any in-memory elements.

3. Delete the application element cache files (*.auc) from the Local Application Data folder (located in %LocalAppData%) to remove the on-disk elements.

Here are two facts to remember about actions:

The actions that are available depend on the type of node you select.

You can select multiple nodes and perform actions simultaneously on all the nodes selected.

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 earlier 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:

1. Create a new menu item and give it a meaningful name, a label, and Help text.

2. Set the menu item’s Object Type property to Class.

3. Set the menu item’s Object property to the name of the class to be invoked by the add-in.

4. Drag the menu item to the SysContextMenu menu.

5. If you want the action to be available only for certain nodes, modify the verifyItem method on the SysContextMenu class.

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, shown earlier). Figure 2-5 shows a class with the Show All Layers option set. 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.

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 AX 2012 is started.

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-8 shows the resulting project when the settings from Figure 2-7 are used.

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

You can also use several other wizards, such as the AIF Document Service Wizard and the Class Wizard, to create projects. To access these wizards, on the Tools menu, click Wizards.

The Create Upgrade Project feature makes a three-way comparison to establish whether an element has any upgrade conflicts. It compares the original version with both the customized version and the updated version. If a conflict is detected, the element is added to the project.

The resulting project provides a list of elements to update based on upgrade conflicts between versions. You can use the Compare tool, described later in this chapter, to see the conflicts in each element. Together, these features provide a cost-effective toolbox to use when upgrading. For more information about code upgrade, see “Microsoft Dynamics AX 2012 White Papers: Code Upgrade” at http://www.microsoft.com/download/en/details.aspx?id=20864.

To create an upgrade project, click Tools > Code Upgrade > Detect Code Upgrade Conflicts.

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.

When the Development Workspace opens, the property sheet is visible by default. If you close it, you can open it again anytime by pressing Alt+Enter or by clicking the Properties button on the toolbar of the Development Workspace. The property sheet automatically updates itself to show properties for any element selected in the AOT. You don’t have to open the property sheet manually for each element; you can leave it open and browse the elements. Figure 2-9 shows the property sheet for the TaxSpec class. The two columns are the key and value pairs for each property.

Figure 2-10 shows the Categories tab for the class shown in Figure 2-9. On this tab, related properties are categorized. For elements with many properties, this view can make it easier to find the right property.

Read-only properties appear in gray. Just like files in the file system, elements contain information about who created them and when they were modified. Elements that come from Microsoft all have the same time and user stamps.

The default sort order places related properties near each other. Categories were introduced in an earlier version of Microsoft Dynamics AX to make finding properties easier, but you can also sort properties alphabetically by setting a parameter in the Options form.

You can dock the property sheet on either side of the screen by right-clicking the title bar. Docking ensures that the property sheet is never hidden behind another tool.

The X++ code editor is a basic text editor that supports color coding and IntelliSense.

Send to mail recipient.

Send to file.

Generate code for standard code patterns such as main, construct, and parm methods.

Open the AOT for the element that owns the method.

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

The technology behind the label system is simple. All text resources are kept in a Unicode-based label files that are named with three-letter identifiers. In AX 2012, the label files are managed in the AOT and distributed by using model files. Figure 2-12 shows how the Label Files node in the AOT looks with multiple label files and the en-us language identifier.

The underlying source representation is a simple text file that follows this naming convention:

Ax<Label file identifier><Locale>.ALD

The following are two examples, the first showing a U.S. English label file and the second a Danish label file:

Axsysen-us.ALD

Axtstda.ALD

Each text resource in the label file has a 32-bit integer label ID, label text, and an optional label description. The structure of the label file is simple:

@<Label ID><Label text>

[Label description]

Figure 2-13 shows an example of a label file.

This simple structure allows for localization outside of AX 2012 with third-party tools. The AOT provides a set of operations for the label files, including an Export To Label file that can be used to extract a file for external translation.

You can create new label files by using the Label File Wizard, which you access directly from the Label Files node in the AOT, or from the Tools menu by pointing to Wizards > Label File Wizard. The wizard guides you through the steps of adding a new label file or a new language to an existing label file. After you run the wizard, the label file is ready to use. If you have an existing .ald file, you can also create the appropriate entry in the AOT by using Create From File on the context menu of the Label Files node in the AOT.

Consider the following tips for working with label files:

When naming a label file, choose a three-letter ID that has a high chance of being unique, such as your company’s initials. Don’t choose the name of the layer, such as VAR or USR. Eventually, you’ll probably merge two separately developed features into the same installation, a task that will be more difficult if the label file names collide.

When referencing existing labels, feel free to reference labels in the label files provided by Microsoft, but avoid making changes to labels in these label files because they are updated with each new version of Microsoft Dynamics AX.

On the Tools menu, point to Label > Label Editor.

On the X++ code editor toolbar, click the Lookup Label > Text button.

On text properties in the property sheet, click the Lookup button.

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.

In addition to finding and creating new labels, you can 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:

When reusing a label, make sure that the label means what you intend it to in all languages. Some words are homonyms (words that have many meanings), and they naturally translate into many different words in other languages. For example, the English word can is both a verb and a noun. Use the description column to note the intended meaning of the label.

When creating a new label, ensure that you use complete sentences or other stand-alone words or phrases. Don’t construct complete sentences by concatenating labels with one or two words because the order of words in a sentence differs from one language to another.

Click here to view code image

// 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++:

Always create user interface text by using a label. When referencing labels from X++ code, use double quotation marks.

Never create system text such as file names by using a label. When referencing system text from X++ code, use single quotation marks. You can place system text in macros to make it reusable.

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 compiler also produces a list of the following information:

Compiler errors These prevent code from compiling and should be fixed as soon as possible.

Compiler warnings These typically indicate that something is wrong in the implementation. See Table 2-4, later in this section, for a list of example compiler warnings. Compiler warnings can and should be addressed. Check-in attempts with compiler warnings are rejected unless specifically allowed in the version control system settings.

Tasks (also known as to-dos) The compiler picks up single-line comments that start with TODO. These comments can be useful during development for adding reminders, but you should use them only in cases in which implementation can’t be completed. For example, you might use a to-do comment when you’re waiting for a check-in from another developer. Be careful when using to-do comments to postpone work, and never release code unless all to-dos are addressed. For a developer, there is nothing worse than debugging an issue and finding a to-do comment indicating that the issue was already known but overlooked.

Best practice deviations The Best Practices tool carries out more complex validations. For more information, see the “Best Practices tool” section later in this chapter.

The Compiler Output window provides access to every issue found during compilation, as shown in Figure 2-15. The window presents one list of all relevant errors, warnings, best practice deviations, and tasks. Each type of message can be disabled or enabled by using the respective buttons. Each line in the list contains information about each issue that the compiler detects, a description of the issue, and its location.

You can export the contents of the Compiler Output window. This capability is useful if you want to share the list of issues with team members. The exported file is an HTML file that can be viewed in Internet Explorer or reimported into the Compiler Output window in another AX 2012 session.

In the Compiler Output window, click Setup > Compiler to define the types of issues that the compiler should report. Compiler warnings are grouped into four levels, as shown by the examples in Table 2-4. Each level represents a certain level of severity, with 1 being the most critical and 4 being recommended to comply with best practices.

You avoid less-than-obvious pitfalls. Following best practices helps you avoid many obstacles, even those that appear only in borderline scenarios that would otherwise be difficult and time consuming to detect and test. Using best practices allows you to take advantage of the combined experience of Microsoft Dynamics AX expert developers.

Your learning curve is flattened. When you perform similar tasks in a standard way, you are more likely to be comfortable in an unknown area of the application. Consequently, adding new resources to a project is more cost effective, and downstream consumers of the code can make changes more readily.

You are making a long-term investment. Code that conforms to standards is less likely to require rework during an upgrade process, whether you’re upgrading to AX 2012, installing service packs, or upgrading to future releases.

You are more likely to ship on time. Most of the problems developers face when implementing a solution in Microsoft Dynamics AX have been solved at least once before. Choosing a proven solution results in faster implementation and less regression. You can find solutions to known problems in both the Developer Help section of the SDK and in the code base.

The AX 2012 SDK contains an important discussion about conforming to best practices in AX 2012. Constructing code that follows proven standards and patterns can’t guarantee a project’s success, but it minimizes the risk of failure because of late, expensive discovery, and it decreases the long-term maintenance cost. The AX 2012 SDK is available at http://msdn.microsoft.com/en-us/library/aa496079.aspx.

The Best Practices tool is a powerful supplement to the best practices discussion in the SDK. This tool is the MorphX version of a static code analysis tool, similar to FxCop for the Microsoft .NET Framework. The Best Practices tool is embedded in the compiler, and the results are reported in the Compiler Output window the same way as other messages from the compilation process.

The purpose of static code analysis is to detect defects and risky coding patterns in the code automatically. The longer a defect exists, the more costly it becomes to fix—a bug found in the design phase is much cheaper to correct than a bug in shipped code running at several customer sites. The Best Practices tool allows any developer to run an analysis of his or her code and application model to ensure that it conforms to a set of predefined rules. Developers can run analysis during development, and they should always do so before implementations are tested. Because an application in AX 2012 is much more than just code, the Best Practices tool also performs static analysis on the metadata—the properties, structures, and relationships that are maintained in the AOT.

The Best Practices tool displays deviations from the best practice rules, as shown earlier in Figure 2-15. Double-clicking a line on the Best Practices tab opens the X++ code editor on the violating line of code or, if the Best Practices violation is related to metadata, it will open the element in an AOT window.

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:

Errors The majority of the rules focus on errors. Any check-in attempt with a best practice error is rejected. You must take all errors seriously and fix them as soon as possible.

Warnings Following a 95/5 rule for warnings is recommended. This means that you should treat 95 percent of all warnings as errors; the remaining 5 percent constitute exceptions to the rule. You should provide valid explanations in the design document for all warnings you choose to ignore.

Information In some situations, your implementation might have a side effect that isn’t obvious to you or the user (for example, if you assign a value to a variable but you never use the variable again). These are typically reported as information messages.

//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:

Dangerous API exceptions When exceptions exist that are impossible to detect automatically, examine each error to ensure the correct implementation. Dangerous application programming interfaces (APIs) are often responsible for such exceptions. A dangerous API is an API that can compromise a system’s security when used incorrectly. If a dangerous API is used, a suppressible error is reported. You can use some so-called dangerous APIs when you take certain precautions, such as using code access security (CAS). You can suppress the error after you apply the appropriate mitigations.

False positives About 5 percent of all warnings are false positives and can be suppressed. Note that only warnings caused by actual code can be suppressed this way, not warnings caused by metadata.

After you set up the best practices, the compiler automatically runs the best practices check whenever an element is compiled. The results are displayed in 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, you add the violation 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. For more information, see “Best Practice Checks” at http://msdn.microsoft.com/en-us/library/aa874347.aspx.

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:

Click here to view code image

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.

AX 2012 client

AOS

Business Connector (BC.NET)

For other debugging scenarios, such as web services, Microsoft SQL Server Reporting Services (SSRS) reports, and Enterprise Portal web client, see Chapter 3, “AX 2012 and .NET.”

You must enable debugging for each component as follows:

In the Development Workspace, on the Tools menu, click Options > Development > Debug, and then select When Breakpoint in the Debug Mode list.

From the AOS, open the Microsoft Dynamics AX Server Configuration Utility under Start > Administrative Tools > Microsoft Dynamics AX 2012 Server Configuration. Create a new configuration, if necessary, and then select the check box Enable Breakpoints to debug X++ code running on this server.

For Enterprise Portal code that uses the BCPROXY context to run interpreted X++ code, in the Microsoft Dynamics AX Server Configuration Utility, create a new configuration, if necessary, and select the check box Enable Global Breakpoints.

Ensure that you are a member of the local Windows security group named Microsoft Dynamics AX Debugging Users. This is normally ensured by using setup, but if you did not set up AX 2012 by using your current account, you need to do this manually through Edit Local Users And Groups in 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 AX 2012 and that other AX 2012 components can access them and break where you want them to.

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

The Reverse Engineering tool can generate a Unified Modeling Language (UML) data model, a UML object model, or an entity relationship data model, including all elements from a private or shared project. To open the tool, in the Projects window, right-click a project or a perspective, and point to Add-Ins > Reverse Engineer. You can also open the tool by selecting Reverse Engineer from the Tools menu. In the dialog box shown in Figure 2-18, you must specify a file name and model type.

When you click OK, the tool uses the metadata for all elements in the project to generate a Visio document that opens automatically. You can drag elements from the Visio Model Explorer onto the drawing surface, which is initially blank. Any relationship between two elements is automatically shown.

The UML data 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 AX 2012 are generated as UML attributes. All attributes are marked as public to reflect the nature of fields in AX 2012. 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 braces.

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

If the relationship is validating (the Validate property is set to Yes), the Aggregation property is set to Shared. This is also known as a UML aggregation, represented by a white diamond.

If a cascading delete action exists between the two tables, a composite association is added to the model. A cascading delete action ties the lifespan of two or more tables and is represented by a black diamond.

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 name of an association endpoint is the name of the relationship. The names and types of all fields in the relationship appear in braces.

The UML object 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 AX 2012 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.

For more information about the elements in a UML diagram, see “UML Class Diagrams: Reference” at http://msdn.microsoft.com/en-us/library/dd409437.aspx.

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

To access the Table Browser tool, right-click any of the following types of items in the AOT, and then point to Add-Ins > Table Browser:

Tables

Tables listed as data sources in forms, queries, and data sets

System tables listed in the AOT under System DocumentationTables

Figure 2-22 shows the Table Browser tool when it is started from the CustTrans table. In addition to the querying, sorting, and filtering capabilities provided by the grid control, you can type an SQ SELECT statement directly into the form by using X++ SELECT statement syntax and see a visual display of the result set. This tool is a great way to test complex SELECT statements. It fully supports grouping, sorting, aggregation, and field lists.

You can also choose to see only the fields from the auto-report field group. These fields are printed in a report when the user clicks Print in a form with this table as a data source. Typically, these fields hold the most interesting information. This option can make it easier to find the values you’re looking for in tables with many fields.

You can start the Find tool, shown in Figure 2-23, from any node in the AOT by pressing Ctrl+F or by clicking Find on the context menu. The Find tool supports multiple selections in the AOT.

On the Name & Location tab, you define what you’re searching for and where to look:

In the Search list, the options are Methods and All Nodes. If you choose All Nodes, the Properties tab appears.

The Named box limits the search to nodes with the name you specify.

The Containing Text box specifies the text to look for in the method, expressed as a regular expression.

If you select the Show Source Code check box, results include a snippet of source code containing the match, making it easier to browse the results.

By default, the Find tool searches the node (and its subnodes) selected in the AOT. If you change focus in the AOT while the Find tool is open, the Look In value is updated. This is quite useful if you want to search several nodes by using the same criterion. You can disable this behavior by clearing the Use Selection check box.

On the Date tab, you specify additional ranges for your search, such as Modified Date and Modified By.

On the Advanced tab, you can specify more advanced settings for your search, such as the layer to search, the size range of elements, the type of element, and the tier on which the element is set to run.

On the Filter tab, shown in Figure 2-24, you can write a more complex query by using X++ and type libraries. The code in the Source text box is the body of a method with the following profile:

Click here to view code image

boolean FilterMethod(str _treeNodeName,
                     str _treeNodeSource,
                     XRefPath _path,
                     ClassRunMode _runMode)

The example in Figure 2-24 uses the class SysScannerClass to find any occurrence of the ttsAbort X++ keyword. The scanner is primarily used to pass tokens into the parser during compilation. Here, however, it detects the use of a particular keyword. This tool is more accurate (though slower) than using a regular expression because X++ comments don’t produce tokens.

The Properties tab appears when All Nodes is selected in the Search list. You can specify a search range for any property. Leaving the range blank for a property is a powerful setting when you want to inspect properties: it matches all nodes, and the property value is added as a column in the results, as shown in Figure 2-25. The search begins when you click Find Now. The results appear at the bottom of the dialog box as they are found.

Double-clicking any line in the result set opens the X++ code editor and sets the focus on the code example that matches. When you right-click the lines in the result set, a context menu containing the Add-Ins menu opens.

The comparison shows changes to elements, which can be modified in three ways:

A metadata property can be changed.

X++ code can be changed.

The order of subnodes can be changed, such as the order of tabs on a form.

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

Standard layered version types These include SYS, SYP, GLS, GLP, FPK, FPP, SLN, SLP, ISV, ISP, VAR, VAP, CUS, CUP, USR, and USP.

Old layered version types (old SYS, old SYP, and so on) If a baseline model store is present, elements from the files are available here. This allows you to compare an older version of an element with its latest version. For more information about layers and the baseline model store, see Chapter 21, “Application models.”

Version control revisions (Version 1, Version 2, and so on) You can retrieve any revision of an element from the version control system individually and use it for comparison. The version control system is explained later in this chapter.

Best practice washed version (Washed) A few simple best practice issues can be resolved automatically by a best practice “wash.” Selecting the washed version shows you how your implementation differs from best practices. To get the full benefit of this, select the Case Sensitive check box on the Advanced tab.

Export/import file (XPO) Before you import elements, you can compare them with existing elements (which will be overwritten during import). You can use the Compare tool during the import process (Command > Import) by selecting the Show Details check box in the Import dialog box and right-clicking any elements that appear in bold. Objects in bold already exist in the application.

Upgraded version (Upgraded) MorphX can automatically create a proposal for how a class should be upgraded. The requirement for upgrading a class arises during a version upgrade. The Create Upgrade Project step in the Upgrade Checklist automatically detects customized classes that conflict with new versions of the classes. A class is conflicting if you’ve changed the original version of the class, and the publisher of the class has also changed the original version. MorphX constructs the proposal by merging your changes with the publisher’s changes to the class. MorphX requires access to all three versions of the class—the original version in the baseline model store, a version with your changes in the current layer in the baseline model store, and a version with the publisher’s changes in the same layer as the original. The installation program ensures that the right versions are available in the right places during an upgrade. Conflict resolution is shown in Figure 2-27.

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

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

Show Differences Only All equal nodes are suppressed from the view, making it easier to find the changed nodes. This option is selected by default.

Suppress Whitespace White space, such as spaces and tabs, is suppressed into a single space during the comparison. The Compare tool can ignore the amount of white space, just as the compiler does. This option is selected by default.

Case Sensitive Because X++ is not case sensitive, the Compare tool is also not case sensitive by default. In certain scenarios, case sensitivity is required and must be enabled, such as when you’re using the best practice wash feature mentioned earlier in this section. This option is cleared by default.

Show Line Numbers The Compare tool can add line numbers to all X++ code that is displayed. This option is cleared by default but can be useful during an upgrade of large chunks of code.

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 sign (≠) on a red and blue background indicates that the nodes are different in the two versions.

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.

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:

Tutorial_Comparable This class implements the SysComparable interface. Basically, it creates a text representation of a customer.

Tutorial_CompareContextProvider This class implements the SysCompareContextProvider interface. It provides the context for comparison. For example, it creates a Tutorial_Comparable object for each customer, sets the default comparison options, and handles context menus.

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

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.

Click here to view code image

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

Here are a couple of typical scenarios for using the Cross-Reference tool:

You want to find usage examples. If the product documentation doesn’t help, you can use the Cross-Reference tool to find real implementation examples.

You need to perform an impact analysis. If you’re changing an element, you need to know which other elements are affected by your change.

You must update the Cross-Reference tool regularly to ensure accuracy. The update typically takes several hours. The footprint in a database is about 1.5 gigabytes (GB) for a standard application.

To update the Cross-Reference tool, on the Tools menu, point to > Cross-Reference > Periodic > Update. Updating the Cross-Reference tool also compiles the entire AOT because the compiler emits cross-reference information.

In addition to the main cross-reference information, two smaller cross-reference subsystems exist:

Data model Stores information about relationships between tables. It is primarily used by the query form and the Reverse Engineering tool.

Type hierarchy Stores information about class and data type inheritance.

For more information about these subsystems and the tools that rely on them, see the AX 2012 SDK (http://msdn.microsoft.com/en-us/library/aa496079.aspx).

The information that the Cross-Reference tool collects is quite comprehensive. You can find a complete list of cross-referenced elements by opening the AOT, expanding the System Documentation node, and clicking Enums and then xRefKind. When the Cross-Reference tool is updating, it scans all metadata and X++ code for references to elements of the kinds listed in the xRefKind subnode.

To access usage information, right-click any element in the AOT and point to Add-Ins > Cross-Reference > Used By. If the option isn’t available, either the element isn’t used or the cross-reference hasn’t been updated.

Figure 2-31 shows where the prompt method is used on the RunBaseBatch class.

When you view cross-references for a class method, the Application hierarchy tree is visible, so that you can see whether the same method is used on a parent or subclass. For types that don’t support inheritance, the Application hierarchy tree is hidden.

Using a version control system offers several benefits:

Revision history of all elements All changes are captured, along with a description of the change, making it possible to consult the change history and retrieve old versions of an element.

Code quality enforcement The implementation of version control in AX 2012 enables a fully configurable quality standard for all check-ins. With the quality standard, all changes are verified according to coding practices. If a change doesn’t meet the criteria, it is rejected.

Isolated development Each developer can have a local installation and make all modifications locally. When modifications are ready, they can be checked in and made available to consumers of the build. A developer can rewrite fundamental areas of the system without causing instability issues for others. Developers are also unaffected by any downtime of a centralized development server.

Even though using a version control system is optional, it is strongly recommended that you consider one for any development project. AX 2012 supports three version control systems: Visual SourceSafe 6.0 and TFS, which are designed for large development projects, and MorphX VCS. MorphX Version Control System (VCS) is designed for smaller development projects that previously couldn’t justify the additional overhead that using a version control system server adds to the process. Table 2-8 shows a side-by-side comparison of the version control system options.

The elements persisted on the version control server are file representations of the elements in the AOT. The file format used is the standard Microsoft Dynamics AX export format (.xpo). Each .xpo file contains only one root element.

There are no additional infrastructure requirements when you use MorphX VCS, which makes it a perfect fit for partners running many parallel projects. In such setups, each developer often works simultaneously on several projects, toggling between projects and returning to past projects. In these situations, the benefits of having a change history are enormous. With just a few clicks, you can enable MorphX VCS to persist the changes in the business database. Although MorphX VCS provides many of the same capabilities as a version control server, it has some limitations. For example, MorphX VCS does not provide any tools for maintenance, such as making backups, archiving, or labeling.

In contrast, Visual SourceSafe and TFS are designed for large projects in which many developers work together on the same project for an extended period of time (for example, an independent software vendor building a vertical solution).

Figure 2-32 shows a typical deployment using Visual SourceSafe or TFS, in which each developer locally hosts the AOS and the database. Each developer also needs a copy of all .xpo files. When a developer communicates with the version control server, the .xpo files are transmitted.

You can create an element in two ways:

Create a new element.

Customize an existing element, resulting in an overlayered version of the element. Because elements are stored for each layer in the version control system, customizing an element effectively creates a new element.

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.

Compiler errors

Compiler warnings

Compiler tasks

Best practice errors

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.

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.

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 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 is divided into three operations that happen automatically in the following sequence:

1. The latest files are copied from the version control server to the local disk.

2. The files are imported into the AOT.

3. The imported files are compiled.

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.

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 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 available with MorphX VCS.

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 AX 2012 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.

For each revision, 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.

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

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

1. Use the CombineXPOs command-line utility to combine all .xpo files into one. This step makes the .xpo file consumable by AX 2012. AX 2012 requires all referenced elements to be present in the .xpo file or to already exist in the AOT to maintain the references during import.

2. Import the new .xpo file by using the command-line parameter -AOTIMPORTFILE=<FileName.xpo>-MODEL=<Model Name> to Ax32.exe. This step imports the .xpo file and compiles everything. After this step is complete, the new model is ready in the model store.

3. Export the model to a file by using the axutil command-line utility: axutil export/model:<model name> /file:<model file name>.

4. Follow these steps for each layer and each model that you build.

The build process doesn’t apply to MorphX VCS.

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.