Chapter 18. Code Upgrade

The objectives of this chapter are to:

  • Provide a high-level overview of the Microsoft Dynamics AX 2009 code upgrade process.

  • Explain the significance of code upgrade in Dynamics AX.

  • Define different types of conflicts and describe how to resolve them.

  • Introduce the code upgrade toolset.

  • Discuss the Smart Customization techniques that can help reduce the cost of upgrade.

Introduction

In Dynamics AX, code upgrade involves finding and resolving conflicts that result from customizations so that an upgraded version of Dynamics AX can successfully use those customizations. The code upgrade process is initialized from the Dynamics AX Upgrade checklist. Code upgrade can take place during a major version upgrade or when you’re applying a service pack or hotfix. You can also run the code upgrade tools separately to detect Trustworthy Computing violations or issues with record ID and table ID references, topics that are covered in more depth later in this chapter.

This chapter begins with a discussion of the terminology used in code upgrade and the reasons code upgrade is necessary and then describes conflicts and explains how they’re introduced. Next, the chapter describes the tools used to find and organize conflicts, and it provides some tips that can help you resolve them. Finally, the chapter describes how to avoid conflicts and the related workload by using Smart Customization techniques when you’re customizing Dynamics AX.

Terminology

Before delving into the details about code upgrade, you need to understand the terms used to describe the process.

  • Element. A type definition in the Application Object Tree (AOT). For example, tables, classes, forms, and reports are elements. Elements are sometimes called application objects.

  • Original. Version of the element before it was customized. Original is usually the version delivered by Microsoft—or the independent software vendor (ISV) or Value Added Reseller (VAR).

  • Yours. Original installation including customization you introduce (i.e., customization you introduce on behalf of the business you work for).

  • Theirs. Original version including updates that Microsoft or the ISV or VAR has made.

  • Current. Version created by merging the Original version, the Yours version, and the Theirs version.

  • Layer. A file that contains all the Dynamics AX business logic (elements such as forms, tables, reports, and so on).

  • Customization. In the context of code upgrade, one or more changes that have been made to an element in the AOT, such as adding a field to a table.

  • Overlayering. A method of customization in which an Original element is copied into a current layer and modified; overlayering can lead to conflicts during the upgrade process, and you should use it carefully. See the section "Smart Customizations" at the end of this chapter for more information about ways to avoid overlayering.

  • Conflict. A mismatch that occurs when the customized definition of an element clashes with the new definition. Conflicts are typically identified during the system upgrade process; they can occur between layers, because of Trustworthy Computing errors, and from errors in record ID and table ID references.

Why Code Upgrade Is Necessary

One of the strengths of Dynamics AX is that it can be extensively customized to suit the needs of an individual business. In fact, because of the layered architecture in Dynamics AX, licensed parties can tailor the entire code base to fit their organization’s requirements. When a business upgrades to a newer version of Dynamics AX or installs a service pack, however, it can encounter conflicts that occur because both Microsoft and the business have made changes to the same element (e.g., the metadata of a form or a report). Conflicts require manual intervention to ensure that both the business customizations (the Yours version) and the new version (the Theirs version) work properly when the business rolls out an upgraded version of Dynamics AX (the Current version).

Note

Note

If you’re working with the Microsoft .NET Framework, you don’t encounter such conflicts because applications can’t change the implementation of the .NET Framework. They are limited to using the APIs the framework provides, so a similar code upgrade process isn’t necessary.

You must develop Dynamics AX customizations carefully, to avoid potential conflicts when possible or to make them easier to manage during the upgrade process. You can find out more about best practices for developing customization in the section "Smart Customizations" at the end of this chapter.

Role of Customization

Imagine that your business has implemented a customized version of Dynamics AX 4.0 (the circle Yours and the box Customized Dynamics AX 4.0 in Figure 18-1). Your business decides to upgrade to Dynamics AX 2009 (Theirs and Dynamics AX 2009 in Figure 18-1) while keeping the customizations it has developed intact. During the upgrade, you have to merge the customizations made in Yours with the changes made in Theirs to be able to continue to use the functionality from both versions (Current, Customized Dynamics AX 2009 in Figure 18-1).

Top-level view of code upgrade

Figure 18-1. Top-level view of code upgrade

Obviously, Dynamics AX 2009 includes changes, some of which might clash with the customization in Yours, resulting in one or more conflicts. You must resolve the conflicts before you can continue with the version upgrade.

Note

Note

Keep in mind that from the system life cycle perspective, even releases of service packs and hotfixes require code upgrade.

Role of Layers

Layers contain the definition of the product, including the database schema and business logic, and are part of what enables developers to customize Dynamics AX so extensively. The changes to the contents of the layers (that is, AOT elements) during customization can cause conflicts, and these conflicts must be resolved during the code upgrade process. (To find out more about the application model layering system in Dynamics AX, refer to Chapter 1.)

Figure 18-2 can help you visualize a layer and the elements it contains.

Representation of the SYS layer and the elements it contains

Figure 18-2. Representation of the SYS layer and the elements it contains

All Dynamics AX elements that Microsoft delivers are stored in layers that only Microsoft can access. These layers include SYS, SYP, GLS, GLP, HFX, SL1, SL2, and SL3. The most important thing for you to understand when customizing Dynamics AX is that when you customize an element, you are creating a modified copy of that element in another layer. This method of customization, called overlayering, frequently results in conflicts. Depending on the type of element that is modified, the scope and potential impact of the overlaying differs.

The effect of the overlaying varies by element type because different AOT elements have different sizes. For example, class methods, table methods, and table fields are smaller than menus and queries, which in turn are smaller than forms and reports. If you customize a form or a report, the entire form or report is copied into your current layer. When you modify the code of a single class method, only this single class method is copied into your current layer (creating Yours).

Tip

Tip

Look at the status bar to see which layer you’re working on.

To get a sense of the size of an AOT element, enable the AOT layer indicator: from the Microsoft Dynamics AX drop-down menu, point to Tools and then Options. On the Development tab, select Show All Layers from the Application Object Layer drop-down menu. Each element has a layer indicator in parentheses—for example, (SYS). A node without a layer indicator is contained within its parent. An element containing many child nodes is more likely to cause conflicts when customized than an element without any child nodes.

Overlayering and Conflicts

Consider a situation in which you customize Field A, Menu A, and Form A to create the Yours version of Dynamics AX 4.0. When you customize these elements, they are copied into the layer you’re currently working in (USR in this case). The resulting overlayering is shown in Figure 18-3. As you can see in Figure 18-3, the customized versions of Field A, Menu A, and Form A have been automatically copied into the upper layer (USR), overshadowing their definition in the lower layer (SYS).

Overlayering conflicts

Figure 18-3. Overlayering conflicts

Assume that during the development of a new version of Dynamics AX, Microsoft changes Field A, Method B, Menu B, Query B, and Form A, as indicated in Figure 18-4.

Hypothetical changes made by Microsoft in a new version of Dynamics AX

Figure 18-4. Hypothetical changes made by Microsoft in a new version of Dynamics AX

When your business upgrades to the new version, you have to merge the customizations you made (Figure 18-3) with the changes Microsoft introduced (Figure 18-4). Figure 18-5 shows the conflicts created by the differences between your customization and Microsoft’s new version of Field A and Form A.

Conflicts in Field A and Form A resulting from customer changes in the USR layer and Microsoft changes in the SYS layer

Figure 18-5. Conflicts in Field A and Form A resulting from customer changes in the USR layer and Microsoft changes in the SYS layer

As you can see in the figures, conflicts have occurred where you have made changes (Yours in Figure 18-3) and where Microsoft has (Theirs in Figure 18-4): Field A and Form A. You must find and resolve the conflicts so you can successfully merge the different versions. After a successful merge, Field A and Form A become Field ACurrent and Form ACurrent (Figure 18-5). You must then test the merged changes.

As long as the overlayered elements haven’t been changed in the Theirs version—Menu A in this example—no additional work is required: Menu ACurrent is the same as Menu AYours. The same concept applies to elements that have been changed in the Theirs version but not in the Yours version—Menu B and Query B in this example.

The cost of merging—in both time and money—can be substantial when many conflicts occur. That is one of the reasons you should apply the Smart Customization techniques described later in this chapter when you’re customizing Dynamics AX.

Starting a Code Upgrade

After the upgrade preparation work has been completed, the next major step in the upgrade process is code upgrade. Assume that you are upgrading a customized version of Dynamics AX 4.0 to Dynamics AX 2009. Here’s how you proceed. Starting from the Dynamics AX Upgrade checklist tool, you use the conflict detection tool (formally known as the Detect Code Upgrade Conflicts tool) to find the conflicts between layers and (optionally) to identify Trustworthy Computing violations and record ID and table ID reference errors. Any conflicts found are collected into specific upgrade projects. You also use the Element Usage Log report to find elements that are no longer used and can be deleted. Based on the list of conflicts, you can use the Upgrade Estimate report to estimate how much time it will take to complete the upgrade. Armed with this information, you can resolve conflicts using the Compare tool, the AOT property sheet, and the X++ code editor. The AOT continuously mirrors the progress of the upgrade.

Note

Note

You can read more about upgrade preparation, data upgrade, and data migration in the Microsoft Dynamics AX 2009 Upgrade Guide, found on the Using Microsoft Dynamics AX site: http://microsoft.com/dynamics/ax/using.

In this section, we describe the types of conflicts, the conflict detection tool and the conflicts it finds, and the algorithm the tool uses. Then in the next section, "Upgrade Projects," we describe how conflicts are grouped and, where possible, how conflicts are resolved. The Element Usage Log report, Upgrade Estimate report, Compare tool, property sheet, and X++ code editor are described in the "Code Upgrade Tools" section.

Conflict Types

As mentioned earlier, conflicts can occur between elements in layers and can also result from Trustworthy Computing violations and from issues with record ID and table ID references. There are three categories of conflicts:

  • Layer conflicts, including overlayering, code, property, ordering, and deletion conflicts

  • Trustworthy Computing conflicts, including record level security, parameter validation, and dangerous API use

  • Record ID and table ID reference conflicts, including inconsistencies among record ID and table ID relationships

Conflict Detection Tool

The first step of the code upgrade process is to detect all the conflicts between the Theirs and Yours versions. The conflict detection tool (or officially, the Detect Code Upgrade Conflicts tool) finds any conflicts and then generates one or more upgrade projects that collect the conflicts into manageable categories.

The conflict detection tool can find any type of conflict from the three categories of conflicts. You can also have the tool automatically resolve any autoresolvable property conflicts it finds.

The conflict detection tool is available from the Dynamics AX 2009 drop-down menu: ToolsDevelopment ToolsCode UpgradeDetect Code Upgrade Conflicts. Figure 18-6 shows a screen shot of the tool.

Conflict detection tool (also known as the Detect Code Upgrade Conflicts tool)

Figure 18-6. Conflict detection tool (also known as the Detect Code Upgrade Conflicts tool)

Conflict Detection Algorithm

The algorithm used to detect conflicts is straightforward. It searches for elements that exist in both the current layer and the underlying layer. It then compares both versions of the elements. If they differ, the algorithm puts the element (the Current version) into an upgrade project to be resolved. The algorithm can be illustrated as shown in Figure 18-7.

Algorithm that detects conflicts between a customized and a new version of Dynamics AX

Figure 18-7. Algorithm that detects conflicts between a customized and a new version of Dynamics AX

Best Practices

Best Practices

Do your initial code upgrade against an empty database. If you encounter problems, export the customizations, delete them from Dynamics AX, and run the code upgrade again. Then import the customizations and resolve the conflicts manually. Also do your code upgrade one layer at a time.

Upgrade Projects

The conflict detection tool creates upgrade projects. The purpose of an upgrade project is to collect the elements that have conflicts. This categorization, along with special visual indicators, enables you to easily find the elements with conflicts and to resolve them—either manually or by using the autoresolve property conflicts feature in the conflict detection tool. Upgrade projects also help you track the progress of the code upgrade. By default, upgrade projects are located under Private Projects in the AOT projects window.

Depending on the options you select in the conflict detection tool, one or more of the following kinds of upgrade projects are created:

  • Layered upgrade project

  • Framework conflict projects, which are Trustworthy Computing upgrade projects and/or record ID and table ID references upgrade projects

IIn the following sections, we describe some typical conflicts you could find in an upgrade project and suggest ways to resolve them.

Conflicts in Layered Upgrade Projects

The layered upgrade project collects contents conflicts, overlayering conflicts, and delete conflicts. In turn, each type of layered upgrade project contains additional kinds of conflicts.

Note

Note

To be able to find conflicts between layers, your system must be properly configured for upgrade. If your system isn’t configured properly, you get the following message in the Infolog window: "No elements are found in AOD files in the Old directory. The layer conflict project will not be created." For detailed procedures about how to configure your system for upgrade, please refer to the Microsoft Dynamics AX 2009 Upgrade Guide, available for download at http://microsoft.com/dynamics/ax/using.

Contents Conflicts

A contents conflict is a generic type of conflict that categorizes the conflicts that can happen among the contents of a node. A node can contain X++ code, properties, and subnodes. Contents conflicts include property conflicts, code conflicts, and ordering conflicts.

Property conflicts

Generally speaking, a property conflict is a mismatch between property values in the Yours version and the Theirs version as compared to the Original version. There are three types of property conflicts:

  • Autoresolved. Property conflict that has been automatically resolved

  • Autoresolvable. Property conflict that can be resolved but hasn’t been automatically resolved

  • Manually resolvable. Property conflict that must be resolved manually

Resolution Tip

You can automatically resolve many property conflicts by selecting Autoresolve Property Conflicts in the conflict resolution tool. You can usually resolve property conflicts that must be manually resolved by using the property sheet or the Compare tool. Following is a description of how the tool determines whether a property conflict can be automatically resolved and an example that shows the result of an automatically resolved property conflict.

If you enable the Autoresolve Property Conflicts option in the conflict detection tool, eligible property conflicts are automatically resolved and reported in the upgrade project with a yellow visual indicator. (The section "Visual Indicators" later in this chapter includes more information about the various visual indicators.)

The algorithm used to automatically resolve property conflicts is uncomplicated. Property conflicts can be automatically resolved when the property has been changed in either the Yours version or the Theirs version. If the same property has been changed in both the Yours and the Theirs versions and the property values are different, the conflict on the node can’t be automatically resolved. The algorithm is shown in Figure 18-8.

Algorithm used to automatically resolve property conflicts

Figure 18-8. Algorithm used to automatically resolve property conflicts

Table 18-1 shows how some example property conflicts would be resolved.

Table 18-1. Results of Applying Autoresolve Property Conflicts Algorithm to Example Property Conflicts

Property

Original

Yours

Theirs

Autoresolved As

Font size

8

9

8

9

Font color

Blue

Blue

Red

Red

Text

Original

Yours

Theirs

Not autoresolvable (must resolve manually)

If even one property conflict that must be resolved manually occurs on a node, none of the autoresolvable conflicts are resolved.

Code conflict

A code conflict occurs if the same method has been changed in different ways in the Yours and Theirs versions as compared to the Original version.

Resolution Tip

Given the variety of possible code conflicts, the resolutions depend on the source of the conflict. In a simple case in which the Yours version matches the Theirs version, you would simply delete the Yours copy in the upper layer.

A more complicated code conflict would arise if the business has adjusted the Dynamics AX business logic. In this case, the organization must investigate whether to preserve or to update that logic, depending on the changes that Microsoft has made in the new version.

Ordering conflict

An ordering conflict occurs when the order of subnodes has been changed in both the Yours version and the Theirs version as compared to the Original version. The reasons for changing the subnode order are unique to each business, so there is no single way to resolve ordering conflicts. Your development team must investigate and decide whether it wants to preserve the Yours order of the subnodes or to update it to reflect the order in the Theirs version.

Overlayering Conflicts

In an overlayering conflict, a node is changed in the Theirs version, but the Yours version redefines the element containing the node but not the node itself.

Resolution Tip

Resolving this type of conflict is a matter of copying the Theirs version of the node into the Current version.

Delete Conflicts

In a delete conflict, one party has deleted the node and the other has changed it.

Resolution Tip

Depending on the element type, Microsoft either deletes the element or adds the prefix DEL_ to the element name. Elements prefixed with DEL_ are typically tables and fields, and they are required for the data upgrade portion of the version upgrade to succeed. Elements with the DEL_ prefix are deleted in the next release, so if you encounter a delete conflict, you should rework your solution so that it doesn’t depend on any deleted elements.

Conflicts in Framework Conflict Projects

The framework conflict projects collect Trustworthy Computing violations and record ID and table ID reference errors.

Framework conflict projects don’t require the version update configuration to run. These projects are created on top of the Best Practices framework, so you do not need any infrastructure preparation before you run them. (For more information on the Best Practices framework, see Chapter 3.)

Trustworthy Computing Conflicts

The Trustworthy Computing upgrade project collects the following types of conflicts: record level security, parameter validation, use of a dangerous API, reference to an unsigned .NET assembly, and validation of display or edit values. Where possible, we provide tips for resolving these conflicts. As always, you should follow secure coding best practices. For more information about secure coding practices for X++, refer to the Microsoft Dynamics AX X++ Security white paper, which is available from the Microsoft Download Center at http://microsoft.com/Downloads.

Record level security

Record level security builds on the restrictions enforced by user-group permissions. With user-group permissions, you restrict which menus, forms, and reports members of a group can access. Record level security also enables you to restrict the information shown in reports and on forms. However, record level security is bypassed in several situations in which the data binding to a control is performed manually—for example, when you use ListView, TreeView, or a table control to show data. These situations are detected automatically and reported as conflicts, enabling you to pay attention to the potential security issues.

Resolution Tip

Depending on the conflicts, you can resolve record level security violations in several ways. One possible resolution is to manually enable record level security. When a list view, tree view, or table control is populated with data from a query, you must manually enable record level security. In this example, record level security isn’t enabled.

public void run()
{
    CustTable custTable;

    super();

    while select custTable
    {
        listView.add(custTable.name);
    }
}

To resolve this conflict, you have to enable the record level security from code, as shown here.

public void run()
{
    CustTable custTable;

    super();

    // Ensure that RLS is used.
    custTable.recordLevelSecurity(true);

    while select custTable
    {
        listView.add(custTable.name);
    }
}
Parameter validation

One example of a parameter validation conflict is when the user can call the managed code directly with a parameter that isn’t validated.

public void testMethodConflict( str name )
{
    CLRObject clrObj;
    ;
    clrObj = new CLRObject( name );
}

Resolution Tip

To mitigate threats associated with calls to unmanaged code, follow this guideline: always validate the (string) input parameters that are used to create instances of these objects. If an adversary can control which DLL/COM object to use, the adversary can compromise parts of the system through Dynamics AX APIs that would normally be inaccessible. The following example shows how to make the parameter constant, which helps prevent attacks using an injection technique.

public void testMethodResolution()
{
    CLRObject newClrObj;
    #define.Name('test')
    ;
    newClrObj = new CLRObject( #Name );
}
Use of dangerous API

A dangerous API is an API that when used inappropriately can become a threat to the system. When you surface a dangerous API conflict, you should substitute an API that is not classified as dangerous. If a feature must access a dangerous API, you should perform an authorization check to make sure that only trusted code from that feature can use the API in question.

A good example of a dangerous API conflict follows. The method here is using direct access to the database by executing SQL statements through the Statement class API.

void MyFunction( str _value)
{
    DictTable  dictTable  = new DictTable(tableNum(custTable));
    Connection connection = new Connection();
    Statement  statement  = connection.createStatement();
    str sql = strfmt("SELECT * FROM %1 WHERE %2 == %3",
              dictTable.name(DbBackend::Sql),
              fieldStr(Custtable, accountNum),
              _value);
    ;
    statement.executeUpdate(sql);
}

Resolution Tip

To resolve this conflict you should use a proper data access mechanism. For example, use the X++ select statement.

void MyFunctionMitigated( str 20 _value )
{
    CustTable table;
    select table where table.AccountNum == _value;
}
Reference to unsigned .NET assembly

This conflict occurs when you have added a reference to a managed assembly, and that assembly is unsigned.

Resolution Tip

Use the following rules when you add a reference to the .NET assembly in the AOT:

  • The reference must use a fully qualified name.

  • The assembly referenced must be strongly signed.

Validation of display or edit values

If a user has access to a table, the user also has access to all the display methods (from ad hoc reports), as you can see in this example.

display ForecastHasSales hasSalesBudget()
{
    return (select forecastSales
                where forecastSales.itemGroupId == this.itemGroupId).recId != 0;
}

In theory, a display method can expose any data from any table. If a display method returns data from another table (or another row in the same table), it poses a threat—this threat is surfaced as a Trustworthy Computing conflict.

Resolution Tip

To resolve conflicts associated with the use of display and edit methods, follow these steps:

  1. Evaluate each display method that returns data from another row, either in the same table or in a different table.

  2. Determine whether this data poses an information-disclosure threat.

  3. If the data does pose a threat, perform explicit authorization checks and throw an exception if access is unauthorized.

Record ID and Table ID Reference Conflicts

The record ID and table ID reference project collects the following types of conflicts: RecId relation missing, TableId relation missing, field uses RecId, field uses TableId, type extends RecId, and type extends TableId.

Similar to the Trustworthy Computing upgrade project, the record ID and table ID reference upgrade project is created on the top of the best practice check framework and doesn’t require version update to run. For more information about the Best Practices tool, see Chapter 3.

RecId relation missing

This conflict occurs when a table contains a field that uses the RefRecId extended data type (or derived type) but no relation is defined for that field.

Resolution Tip

To resolve a RecId relation missing conflict, either define the missing relation or don’t use RefRecId as an extended data type on the field.

TableId relation missing

This conflict occurs when a table contains a field that uses the RefTableId extended data type (or derived type) but no relation is defined for that field.

Resolution Tip

To resolve a TableId relation missing conflict, either define the missing relation or don’t use RefTableId as an extended data type on the field.

Field uses RecId

This conflict occurs when a table field uses the RecId extended data type.

Resolution Tip

To resolve a field uses RecId conflict, you must use RefRecId or a derived extended data type and define the relation that actually uses this field.

Field uses TableId

This conflict occurs when a table field uses the TableId extended data type.

Resolution Tip

To resolve a field uses TableId conflict, you must use TableRecId or a derived extended data type.

Type extends RecId

This conflict occurs when you create a new extended data type that extends the RecId type.

Resolution Tip

To resolve a type extends RecId conflict, you have to change the extending type to RefRecId.

Type extends TableId

This type of conflict is similar to the type extends RecId conflict. It occurs when an extended data type extends the TableId type.

Resolution Tip

To resolve a type extends TableId conflict, you have to change the extending type to RefTableId.

Upgrade Project Tools

The tools described in this section can help you manage your upgrade projects.

Visual Indicators

To help you find the exact place where a conflict is located and to show you the status of the conflict, Dynamics AX 2009 has added visual indicators to the upgrade project. There are two kinds of visual indicators. The first type reflects the status of the conflict and has three subtypes:

  • Resolved A green box with a check mark

  • Auto resolved A yellow box with a check mark

  • Manually resolvable A red circle with an X

The second type of visual indicator, also three subtypes, can help you navigate the upgrade project and easily find the nodes where conflicts have occurred:

  • Resolved conflict below A green arrow

  • Auto resolved conflict below A yellow arrow

  • Manually resolvable conflict below A red arrow

If there is more than one conflict on a node, the visual indicator points out the most severe one. Conflicts that must be manually resolved are the most severe, followed by conflicts that have been automatically resolved.

Tip

Tip

When you hover over the node with a conflict, you see a tooltip that describes the type of conflict on the node.

Mark As Resolved, Unresolved

This option is dedicated to helping you keep track of the progress you’re making in resolving conflicts. After you review and resolve a conflict, use this option to update the status of the conflict. Select the node in the Upgrade project, open the context menu, point to Add-Ins, and select the appropriate option.

Note

Note

The conflict status shows up in the Upgrade Estimate report and enables easy tracking of the progress of the code upgrade process.

The Mark As Unresolved option can help you when you have to revisit a place in the code, reevaluate the property value, or inspect the order of controls.

Remove Resolved Elements

To create a clear workspace, you can remove elements with resolved conflicts from an upgrade project. Open the context menu from the root of the appropriate upgrade project, and click Remove Resolved Elements.

Rerun Conflict Detection

You might occasionally need to rerun the conflict detection functionality—for example, if you accidentally mark the conflict on a node as resolved. Select the node in the upgrade project, open the context menu, point to Add-Ins, and select the appropriate option.

Caution

Caution

Use the Rerun Conflict Detection option carefully. It overwrites the status of conflicts, which is then reflected in the Upgrade Estimate report.

Code Upgrade Tools

Dynamics AX ships several tools that you can use to plan your code upgrade and resolve the conflicts you find. In this section, we describe the tools you can use to find and resolve these conflicts so that you can successfully merge your customizations with a newer version of Dynamics AX.

Element Usage Log Report

If you have conflicts on forms or reports and you’re not sure anyone uses those elements, you can use the Element Usage Log report to see how often certain elements are used.

The purpose of this tool is to collect information about the usage of forms and reports, elements that can be expensive to upgrade. The log can help you to decide whether you want to invest in upgrading these elements.

The algorithm used to collect usage information is simple. Every time a form or report is opened, the usage is logged in memory.

You can find the Element Usage Log report in the Administration module: ReportsSystem Element Usage Log or in the AOT under ReportsSysUtilElementsLog.

Upgrade Estimate Report

More conflicts in the system mean more development work during upgrade. The Upgrade Estimate report can help you plan the development team’s code upgrade work. As soon as you know the number and type of conflicts you have in your system, you can use the Upgrade Estimate report to give you a good estimate of how much time is needed to resolve the conflicts.

Tip

Tip

The Upgrade Estimate report provides time estimations in fractions of an hour, not in minutes.

You can invoke the Upgrade Estimate report from two places: from the context menu of a root node of an upgrade project and from the Microsoft Dynamics AX drop-down menu under ToolsDevelopment ToolsCode UpgradeEstimation Report. There is an essential difference between these two reports: the estimation report created from the root of the upgrade project considers only those conflicts that are in the particular upgrade project. The estimation report from the Dynamics AX drop-down menu considers conflicts from all upgrade projects you’ve created—that is, the total number of conflicts in your system—which can help you estimate the time required for the entire (layered upgrade, Trustworthy Computing upgrade, and record and table ID references upgrade) code upgrade process.

Dynamics AX has defined default time estimates for each type of conflict. Depending on your level of experience with Dynamics AX, you might want to adapt the predefined values so they better reflect your real world. To change the predefined values, from the root of the upgrade project, open the Upgrade Parameters form. You can edit any of the six default settings to specify custom default values for specific conflict types and object types.

Compare Tool

The Compare tool is the primary tool that can help you resolve the conflicts in your system. To open the Compare tool, select an element in the AOT, open the element’s context menu, and point to Compare (or use the Ctrl+G shortcut after selecting an element in the AOT). Similar to the conflict detection tool, the Compare tool can be used to inspect and resolve conflicts. The Compare tool can compare two different elements, the same element in two different layers, two versions of the same element (if you’re using version control), and two versions of the same element with the original version of the element.

You can also use the Compare tool to resolve conflicts by inserting, deleting, or moving code. For more information about the Compare tool, including procedures, see the Microsoft Dynamics AX 2009 Upgrade Guide, which is available for download from http://microsoft.com/dynamics/ax.

Property Sheet

Sometimes the Compare tool can’t help you resolve conflicts—for example, if one of the parties (Yours or Theirs) has normalized a table that resulted in splitting data sources and caused the removal of the old data sources. In this case, you can use the property sheet to resolve property conflicts and the X++ code editor to resolve code conflicts. For more information about the property sheet, see Chapter 3.

X++ Code Editor

When code changes between the Yours version and the Theirs version are significant and complex, you can’t use the Compare tool to resolve conflicts. Instead, you need to use the X++ code editor to make the code changes that resolve the conflict. For more information about the X++ code editor, see Chapter 3.

Finishing a Code Upgrade

After you have found and resolved all conflicts, test the system to make sure that the code upgrade has succeeded. Testing involves performing unit tests to ensure that users can still execute their most common and vital tasks, that administrators can run system maintenance tasks, and that permission settings are working properly. For more information on unit tests, see Chapter 3 or the Microsoft Dynamics AX 2009 software development kit (SDK) on MSDN. For more information about performing post–code upgrade tests, see the Microsoft Dynamics AX 2009 Upgrade Guide.

Smart Customizations

The goal of Smart Customizations is to provide guidelines that help you customize an application so that you can avoid overlayering and thus minimize conflicts during the upgrade process. Generally, you should try to add new elements instead of changing existing ones. If you must customize the application in a way that causes overlayering, try to change a small element—a class method, for example—instead of a big element, like a form. If you customize a class method, only that class method is affected, and future code upgrades will be smoother. On the other hand, if you update one property on a grid that is placed on a form, the entire form is copied into the layer you’re working on. The large "size" of the copied form means that future upgrades will be more time-consuming.

Following are some specific techniques you can use to avoid overlayering conflicts.

Note

Note

You can see a recording about Smart Customizations on the Channel 9 site, accessible through MSDN.

Using IntelliMorph Technology

Instead of customizing forms and reports, you should use field groups and extended data types, and take advantage of the dynamic rendering functionalities of the IntelliMorph technology. Let’s assume that you add a new field on a table and you want to display it on a form. Instead of customizing the form by adding a new control for the new data field, you can add the field to an existing field group on the table and let IntelliMorph do the work for you. By doing this, you have customized only the field group, not the form or the table. A conflict on a field group has a much lower impact than adding a new control to the form. For more information about using IntelliMorph technology, see the Microsoft Dynamics AX 2009 SDK.

Creating New Elements or Using Class Substitution

As mentioned earlier, you can also avoid overlayering by creating a new element instead of modifying an existing element; new elements don’t overlayer any existing element.

For classes, you should consider using the class substitution technique. Think about this as an implementation of the Liskov Substitution Principle (LSP). When you follow the LSP, you substitute one implementation of a class with another implementation by using inheritance. The class being substituted must have its constructor encapsulated, so the developer has to modify the construction of the original class in only one place. This is why you find static construct methods on most classes in Dynamics AX.

The static construct method is responsible for creating a new instance of a given class. You use this construct method across the application whenever a new instance of a given class is required. You can easily change the behavior of a given class by modifying the construct method and creating an instance of derived type instead of creating an instance of base type. (A similar technique, the extract and override factory method, is commonly used to remove dependencies. You can read more about that technique in the book Working Effectively with Legacy Code by Robert Martin.) In the derived type, you specialize original behavior with the required behavior. This customizes the application by adding new code, resulting in minimum overlayering.

Modifying Stable Application Elements

Finally, you should consider how likely it is that Microsoft, the ISVs, or the VARs you work with (the creators for Theirs) will change a given application element in the future. For example, complicated logic or large elements such as forms are more likely to change than factory methods. Generally speaking, the more complicated the logic, the more likely it is that it could change in the future and cause hard-to-resolve upgrade conflicts.

..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.
Reset