The MorphX Development Environment and Tools

Version control

The Version Control tool in MorphX makes it possible to use a version control system, such as Microsoft Visual SourceSafe or Visual Studio Team Foundation Server (TFS), to keep track of changes to elements in the AOT. The tool is accessible from several places: from the Version Control menu in the Development Workspace, from toolbars in the AOT and the X++ code editor, and from the context menu on elements in the AOT.

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.

TABLE 2-8 Overview of version control systems.

Requirements and features	No version control system	MorphX VCS	Visual SourceSafe	TFS
Application Object Servers required	1	1	1 for each developer	1 for each developer
Database servers required	1	1	1 for each developer	1 for each developer
Build process required	No	No	Yes	Yes
Master file	Model store	Model store	XPOs	XPOs
Isolated development	No	No	Yes	Yes
Multiple checkout	N/A	No	Configurable	Configurable
Change description	No	Yes	Yes	Yes
Change history	No	Yes	Yes	Yes
Change list support (atomic check-in of a set of files)	N/A	No	No	Yes
Code quality enforcement	No	Configurable	Configurable	Configurable

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.

Element life cycle

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

You can create an element in two ways:

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

Quality checks

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:

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

Source code casing

You can set the Source Code Titlecase Update tool, available on the Add-Ins submenu, to execute automatically 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.

Common version control tasks

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

TABLE 2-9 Version control tasks.

Action	Description
Check out an element	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. To see which elements you have currently checked out, on the Microsoft Dynamics AX menu, click Control > Pending Objects. 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.
Undo a checkout	If you decide that you don’t want to modify an element that you checked out, you can undo the checkout. This releases your lock on the element and imports the most recent checked-in revision of the element to undo your changes.
Check in an element	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 later in Figure 2-34 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. The following procedure is recommended for checking in your work: Perform synchronization to update all elements in your environment to the latest version. Verify that everything is still working as intended. Compilation is not enough. Check in the elements.
Create an element	When using version control, you create new elements just as you normally would in a 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 (on the Development Workspace Version Control menu, point to Control > Setup > System Settings). By default, jobs and private projects are not accepted. New elements should follow Microsoft 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.
Rename an element	An element must be checked in to be renamed. Because all references between .xpo files are strictly name-based, all references to renamed elements must be updated. For example, if 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, and thus they are not affected when an element is renamed; in most cases, it is enough to check out the form or report and include it in the check-in to update the .xpo file. You can use the Cross-Reference tool 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 an element is renamed.
Delete an element	You delete an element as you normally would in Microsoft 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.
Get the latest version of an element	If someone else has checked in a new version of an element, you can use the Get Latest option on the context menu to get the version of the element that was checked in most recently. This option isn’t available if you have the element checked out yourself.

Working with labels

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

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

Figure 2-34 shows the Check In dialog box.

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.

Synchronizing elements

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

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

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.

Viewing the synchronization log

The way that you keep track of versions on the client depends on your version control system. Visual SourceSafe requires that AX 2012 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 AX 2012 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 AX 2012.

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.

Showing the history of an element

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

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.

Comparing revisions

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

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.

Viewing pending elements

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

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

Creating a build

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

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 AX 2012 with other version control systems

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

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.