Microsoft Dynamics AX 2012 introduces a new era for managing metadata artifacts.

In previous versions of the product, metadata artifacts were stored in Application Object Data (AOD) files. These files served two purposes. First, they acted as the deployment vehicle for metadata; for example, you could copy an AOD file from the source system to the target system. Second, they provided runtime storage for model elements. The AOD file provided the physical storage for a native indexed sequential access method (ISAM) database that contained the metadata, and the runtime read model elements from this storage.

This method of managing metadata artifacts was not optimal. From a deployment perspective, AOD files didn’t allow side-by-side installation of metadata in the same layer, didn’t contain any structured information about their contents, and couldn’t be digitally signed. From a runtime perspective, the AOD format supported only one table and provided no capability for adding or changing columns. To support the evolution of runtime scenarios, the product had to move toward a relationally correct schema.

In Microsoft Dynamics AX 2012, metadata is stored in the Microsoft SQL Server database along with business data. The tables containing the metadata are called the model store. This change removes all obstacles to providing a relationally correct schema. Elements, such as classes, tables, forms, methods, and controls, in the model store are grouped into models. Each model can be exported to a file-based format with the extension .axmodel. These files are managed assemblies and therefore, support digital signing, which makes them tamper-proof. Model files are the primary deployment vehicle for model elements in Microsoft Dynamics AX 2012.

In previous versions of Microsoft Dynamics AX, independent software vendors (ISVs) sometimes delivered textual source code files (in XPO format) to customers. Releasing source code files is an undesirable practice, but it was used to overcome restrictions on element IDs for combining multiple solutions in the same layer. With Microsoft Dynamics AX 2012, you no longer need to release source code files to customers. Model files do not contain element IDs, you can install multiple models in the same layer, and each model file contains a manifest that describes the model.

In previous versions of Microsoft Dynamics AX, a complete set of AOD files could be deployed in one operation, typically when a solution was moved from a staging system to a production system. The primary concern in this scenario is to reduce downtime. Copying all AOD files in one operation reduced downtime because there was no need to regenerate the Application Object Index (AOI) file or to recompile the application code. To satisfy the same need in Microsoft Dynamics AX 2012, you can export an entire model store in a binary file with the extension .axmodelstore. This file can be imported into the target system, and the system’s downtime is restricted to the time it takes to restart the Application Object Server (AOS).

The Microsoft Dynamics AX 2012 runtime executes a program defined in the MorphX development environment. The program itself is defined as elements.

Unlike most systems, Microsoft Dynamics AX can contain multiple definitions of each element; for example, multiple implementations of the same method. These element definitions are stacked in layers. The Microsoft Dynamic AX runtime uses the element definitions from the highest layer in which they are found. For example, a method defined in the SYS layer (the lowest layer) is not used if another definition of the same method exists in any other layer.

This layered development approach provides several benefits, the most important being the ability to customize the program shipped by Microsoft, Microsoft partners, and ISVs without editing the original source code.

When you start Microsoft Dynamics AX 2012, you specify which layer you want to start in. By default, you start in the USR layer. Any element you create or edit is stored in that layer. If you edit an element that exists in a lower layer, a copy of the element with your edits is moved to your layer. This process is known as over-layering.

Other benefits of layers include the ability to revert to the original definition of an element by deleting the over-layering version. You can also compare versions of an element; for example, to see which lines of code you have inserted. This is particularly useful during upgrade.

The process of editing an element from a higher layer than the current layer is known as under-layering. By design, these edits are routed to the higher layer.

Microsoft Dynamics AX 2012 has 16 metadata layers, each with its own purpose. Table 21-1 describes these layers in alphabetical order.

Within a layer, metadata elements are grouped into models. Models are covered in the following section.

A model is a logical container of metadata elements, such as forms, tables, reports, and methods. For more information about element types, see Chapter 1.

The model store can contain as many models as you want. Figure 21-1 shows the relationship between layers, models, and elements.

Figure 21-1. Layers, models, and elements.

You can have as many models in each layer as you want. This means you can segment your layer into as many models as you like. Here are some development scenarios where this can be useful:

You can get a model in two ways: you can either create one on your own, or you can receive one from someone else. Because you can have as many models as you want in each layer, you can deploy models from several sources in the same layer.

Suppose you are a customer and want to install two ISV solutions that are available in the ISV layer. In previous versions, you would have had a tough choice to make. Either you picked your favorite solution and learned to live without the other one, or you invested in having the two solutions merged into one layer. This merge was technically challenging and costly if updates to either solution were released. In Microsoft Dynamics AX 2012, you just download the two models and then use AXUtil, a command-line utility that is available when you install Microsoft Dynamics AX, to import them. When a new version of either model is released, you simply use AXUtil to update the model.

The layer model element containment hierarchy has one restraint: an element can be defined only once per layer. In other words, you cannot install two models containing a definition of the same element in the same layer on the same system. Here are some examples:

This limitation enables the Microsoft Dynamics AX runtime to select the right version of an element to execute based on the layer in which it’s contained.

You can encounter this limitation in two ways:

All element types have names, and a few element types also have an integer-based ID. The ID is a 32-bit integer and is assigned at installation time. This means that the same element might have a different ID on two different systems.

Two new properties have been introduced to support scenarios in which elements are upgraded or renamed:

AXUtil assigns element IDs when a model is imported, based on the following rules:

This algorithm ensures that IDs are maintained in simple and advanced import scenarios. Consider a scenario where you have delivered several variations of the same solution to multiple customers as AOD or XPO files in Microsoft Dynamics AX 2009. This means that you probably maintain a copy of the source code for each of your customers in order to service them. As the number of customers grows, so does the incentive to consolidate the variations into one common solution. Step 2 in the algorithm ensures that IDs are maintained on the customer’s installation when the customer upgrades from a specialized solution to a common solution.

During regular development, the system maintains IDs, and you do not need to be concerned with them. However, you still need to pay attention to IDs in two situations: when upgrading a model and when moving from test to production. These two situations are covered in the following sections.

Before you implement your solution, you need to create a new model. You can create a model in several ways. You can do so in MorphX through Tools > Model Management > Create model, you can use Windows PowerShell from the Microsoft Dynamics AX 2012 Management Shell, or you can use AXUtil. The examples in this chapter use the latter.

AXUtil create /model:"My Model" /Layer:USR

Notice that you have to specify which layer the model belongs to. A model cannot span layers.

After creating the model, you need to select it. In the status bar in MorphX, you can see the current model. You can change the model by clicking it. All elements that you create in the AOT are contained in the current model.

You can easily see which model an element belongs to by inspecting the element’s properties. You can also enable a model indicator in the AOT on each element in Tools > Options > Development. You can move an element between models in the same layer by right-clicking the element, and then clicking Move to model.

Now that you have your model, you are ready to implement your solution.

When your implementation is complete, it is time to prepare the model for publication. But before you do, you may want to create a MorphX project that contains the elements in your model. You can create the project by using Tools > Model Management > Create project. This allows you to ensure that the model contains what you expect before you publish it. You can also use AXUtil to list the elements in a model.

AXUtil view /model:"My Model" /verbose

Preparing your model for publication consists of the following steps:

AXUtil manifest /model:"My Model" /xml >MyManifest.xml
notepad MyManifest.xml
AXUtil edit /model: "My Model" @MyManifest.xml

AXUtil export /model:"My Model" /file:MyModel.axmodel

AXUtil view /file:MyModel.axmodel /verbose

SN -k mykey.snk
AXUtil export /model:"My Model" /file:MyModel.axmodel /key:mykey.snk

signtool sign /f mycertprivate.pfx /p password MyModel.axmodel

Import model files

If you have received or downloaded a model file, you can import it by using AXUtil. The model file is always imported into the layer it was exported from. It is a best practice to stop the AOS before importing model files.

AXUtil import /file:SomeModel.axmodel

Note

You don’t have to specify file extensions when using AXUtil. The tool automatically adds the right extension if it is omitted. In this book, extensions are included for clarity.

Figure 21-2 shows a model that has been successfully imported into a layer in which a model already exists.

Figure 21-2. Side-by-side installation of two models.

The import operation will be cancelled if one or more elements from the model file are already defined in the layer into which the model is being imported. If you rerun the import operation with the /verbose option, you will get a list of conflicting elements.

AXUtil import /file:SomeModel.axmodel /verbose

You have two options for proceeding with the import: overwrite and push.

Import model files with the overwrite option

You can decide to overwrite existing conflicting elements with the new definitions of the model element from the model file. You do so by specifying the /conflict:overwrite option on the import command:

AXUtil import /file:SomeModel.axmodel /conflict:overwrite

Figure 21-3 shows the result of a successful import using the /conflict:overwrite option. The imported model and the existing model that contained conflicting elements are linked after this operation. The models are linked because the existing model now is partial. The linkage prevents the imported model from being uninstalled unless the existing model is also uninstalled. This option is primarily used when delivering cumulative patches or service packs.

Figure 21-3. Side-by-side installation of two models using the /conflict:overwrite option.

Import model files with the push option

The most typical solution to solve conflicts is the /conflict:push option. This option creates a new virtual model in a higher layer containing the conflicting elements:

AXUtil import /file:SomeModel.axmodel /conflict:push

Figure 21-4 shows the result of a successful import operation using the /conflict:push option. The elements in the virtual model are identical to those imported. In other words, existing models are not affected. After importing the model, log in to the layer containing the virtual model to resolve the conflict. You can use the compare functionality in the AOT to compare the conflicting versions of each element and resolve the conflict.

Figure 21-4. The result of an import operation using the /conflict:push option.

If you resolve all conflicts in the same layer, there is no risk of running out of layers when using the /conflict:push option. However, you may need to move the resolved elements into the same layer manually. For example, if you import a third model that conflicts with elements in the virtual model in Figure 21-4, the resulting virtual model will be created in Layer 3. After you resolve the conflicts in Layer 3, move the elements in Layer 3 to Layer 2. The easiest way to accomplish this is by exporting the elements from Layer 3 to an XPO file, deleting them, and importing them into Layer 2.

By default, the virtual model is created in the layer just above the layer the model is imported into. If you don’t have developer access to that layer, you can force AXUtil to create the virtual model in a different layer (for example the USR layer) by using the /targetlayer option, as shown in the following example:

AXUtil import /file:SomeModel.axmodel /conflict:push /targetlayer:USR

When you receive a newer version of a model and you want to replace the older version in the model store, it is important that you import the new model on top of the existing model. AXUtil automatically detects that the model already exists in the model store and performs the actions that are required to ensure the consistency of the model store:

AXUtil import /file:NewerModel.axmodel

By default, AXUtil import enters upgrade mode when a model with the same name and publisher already exists. Sometimes a model might be renamed or replaced by multiple new models (as the result of segmentation work, for example), or multiple models might be merged into one consolidated model. AXUtil supports upgrading existing models with new models. You can force AXUtil to use this mode by listing the files and models to upgrade, separated by a comma:

AXUtil import /file:f1,f2,f3 /replace:m1,m2,m3,m4,m5

It is a good practice to have a test or staging environment where changes to the system are prepared and tested before being deployed to a live production environment.

The model store provides features that you can use to export all model store metadata to a binary file and import it into a target system. Doing this creates a binary, identical copy of metadata between the two systems, including element IDs. Model store files have the extension .axmodelstore. Besides the metadata, the model store files also contain the compiled pcode and common intermediate language (CIL) code. This means that you do not have to compile the target system.

Figure 21-5 shows the cleanest way of creating and preparing a test environment and deploying it to production. Variations and post-setup tasks to this process exist. For a thorough description, see the Microsoft Dynamics AX 2012 white paper “Deploying Customizations Across Microsoft Dynamics AX 2012 Environments” (http://www.microsoft.com/download/en/details.aspx?id=26571).

Figure 21-5. Creating and preparing a test environment and deploying a model store to production.

AXUtil exportstore /file:ProductionStore.axmodelstore

Net stop AOS60$01
AXUtil importstore /file:ProductionStore.axmodelstore
Net start AOS60$01

AXUtil exportstore /file:TestStore.axmodelstore

AXUtil schema /schemaname:TransferSchema

AXUtil importstore /file:TestStore.axmodelstore /schema:TransferSchema

Net stop AOS60$01

AXUtil importstore /apply:TransferSchema /backupschema:dbo_backup

Net start AOS60$01

The AXUtil utility used in all examples in this chapter provides a command-line interface to the model store commands offered by the model store API. A PowerShell interface is also available from the Microsoft Dynamics AX 2012 Management Shell.

Both these interface implementations use the managed assembly file AXUtilLib.dll. You can also use this assembly if you want to automate any model store operations. The assembly is referenced in X++, so you can easily access the model store API from X++. Some of the most common commands are available from the SysModelStore class.

The model store API also contains a method to generate license keys for a license code in the AOT based on the license holder name and serial number. The following example shows how to invoke this method from a managed website in an automated license purchasing scenario. For more information about how to protect your solution with a license code, see Chapter 14.

using Microsoft.Dynamics.MorphX;
using Microsoft.Dynamics.AX.Framework.Tools.ModelManagement;

protected void Submit_Click(object sender, EventArgs e)
{
    string certPath = @"c:LicensesMyCertPrivate.pfx";
    string licensePath = @"c:Licenses" + Customer.Text + "-license.txt";
    string licenseCodeNameInAot = "MyLicenseCode";
    string certificatePassword = "password";  //TODO: Move to secure storage
    AXUtilContext context = new AXUtilContext();
    AXUtilConfiguration config = new AXUtilConfiguration();

    LicenseInfo licenseInfo = new LicenseInfo(licensePath, certPath,
                    licenseCodeNameInAot, Customer.Text, Serial.Text,
                    null, certificatePassword);
   config.LicenseInfo = licenseInfo;
   AXUtil AXUtil = new AXUtil(context, config);
   if (AXUtil.GenerateLicense())
   {
       Response.AddHeader("Content-Disposition",
                          "attachment;filename=license.txt");
       Response.TransmitFile(licensePath);
       Response.Flush();
       Response.End();
   }
}