Working with Models in Microsoft Dynamics AX 2012

Microsoft Dynamics® AX 2012

Working with models in Microsoft Dynamics AX 2012

Concept Paper

The concepts of models and model files are new to Microsoft Dynamics AX 2012. Their core purpose is to make deployments easier for partners and to enable partners to install multiple solutions—models—in the same layer. This concept paper discusses rules and best practices, and it offers programming guidance to enable partners to take advantage of these capabilities.

August 2011

CCAX2012IC0070

Table of Contents

Overview 3

Naming models (naming, identification) 3

Naming the model file 4

Creating models (sizes, numbers) 4

Developing for parallel models 5

Deploying and handling multiple models (push, reject, overwrite, move) 6

Moving from staging to production environments 6

Glossary of terms 8

Overview

Naming models (naming, identification)

Identification of a model consists of two parts, a name and a publisher name. You should be very crisp on the naming. Changing any of the two later on will make your model appear to Microsoft Dynamics AX 2012 as “another” model, which by default cannot coexist with “your own” then. The publisher name can be omitted. If it is omitted, it will default to an empty string.

A model has a user friendly name as well, “Display Name”, which is used in user interfaces where space is limited. We recommend that you use a clear, descriptive explanatory name. If an explanatory name is omitted, the model identification name is used. “Display Name” does not have to be unique.

A model can be assigned a version number as well. The default version number is “1.0.0.0”.

þ Do carefully select model names. Model names uniquely identify your model and may be used later, for example, for upgrades. The identification of a model consists of the name and the publisher name.
Example: Fleet Management, ACME, Inc.

þ Do select a 5–20 character name that describes the model. The name part is shown in the setup program, but generally not in the IDE (where “display name” is).
Example: Fleet Management

þ Do use a non-empty publisher name in order to avoid potential conflicts with other partner solutions.
Example: ACME, Inc.

þ Do use 2–15 character display name, which in the IDE is the short version of name and publisher name.
Example: Fleet

þ Do consider using a version number for the model. If you do not use versioning, 1.0.0.0 is the default.

þ Do consider using a 10–200 character description of the model. The description will surface in the setup program and inside Microsoft Dynamics AX 2012 from the About box or Tools |Model management |Models installed.

þ Do consider exporting the manifest, that is, all of the properties defining the model, to an XML file. The manifest can be used directly by many tools, such as AXUtil.exe and AX32.exe.

Naming the model file

The name of the model file artifact does not carry any semantics as such. The important information—the unique identification of the model—is embedded in the model file. However, we strongly recommend that you follow the following best practices for naming file artifacts.

þ Select a name that states what is “in the file”.
Example: PublicSector.axmodel

þ Consider using the model name as the file name.
Example: Fleet Management.axmodel

ý Do not use Microsoft Dynamics AX 2009-style layer names, such as axvar.axmodel, because they might conflict with other partners’ files.

Creating models (sizes, numbers)

Use the AXUTIL utility, the model management Windows PowerShell cmdlets, or the Microsoft Dynamics AX 2012 client to create a new model in the model store. Follow the naming guidelines outlined in this paper. The following sample uses axutil.exe to create a Public Sector model with a specific version number, 6.0.0.0, and a user-friendly name (in this example, it is the same as the model name):

AXUTIL CREATE /model:("Public Sector","Microsoft Corporation") /layer:sln /manifest:Version=6.0.0.0

For internal or temporary use, a simpler form may be sufficient, for example:

AXUTIL CREATE /model:"Public Sector" /layer:sln

For some scripting scenarios, such as the nightly build, it is beneficial to pass a manifest file instead. Use the following form to pass a manifest file:

AXUTIL CREATE @model.xml

where model.xml is a model manifest, such as:

<?xml version="1.0" encoding="utf-8"?>

<Name>Public Sector</Name>

<Description>Public Sector for Dynamics AX.</Description>

<Publisher>Microsoft Corporation</Publisher>

<Signed>false</Signed>

<Category>Standard</Category>

<InstallMode>Standard</InstallMode>

</ModelManifest>

Some general rules about models and their content include the following:

ý Do not use the system generated models for anything but sandboxing. Two partners using the system generated model in the same layer cannot be installed in the same layer because they appear equal.

þ Do include label files in your model – Including label files makes the deployment process easier.

þ Do consider creating a separate shared model if you share elements or label files across multiple solutions.

ý Avoid creating models that are too small. Think of models as sellable units, not as a class library.

þ Do sign your model file if it will be used externally.

Developing for parallel models

The single most important rule for two partner solutions—models—to coexist in an installation is that any one element can only exist once in a given layer. Out-of-the-box feature improvements in Microsoft Dynamics AX 2012 help in integrating two solutions, including fine-grained forms and new concepts and installation-specific IDs. The following list offers a few coding best practices to consider as well.

ý Avoid the generic naming of customizations, for example, tables, fields, classes, methods. Even with more granular metadata, name conflicts are still name conflicts.

þ Do consider using partner prefixes in names for concepts and customizations.

þ Do use event subscription whenever applicable so that you do not conflict on same-element as another partner, and you can prevent potential challenges and problems related to upgrading your solution later in the process. An example is the insert/update/delete methods on key tables such as CustTable.

þ Do favor additions over customization with fine-grained concepts, such as tables, classes, and forms.

Deploying and handling multiple models (push, reject, overwrite, move)

The tools for deployment, axutil.exe, and the model management Windows PowerShell cmdlets support different ways to install models. Consider the following best practices for deploying and handling multiple models (syntax for axutil.exe is shown).

þ Do install models from lower layers before installing models from upper layers.

þ Do use /conflict:reject mode by default because it immediately identifies whether the imported model is in conflict with a model in the store.

ý Avoid using /conflict:overwrite mode. While using /conflict:overwrite may seem feasible at first, it can re-introduce all the pitfalls of merging solutions using AOD –files in previous versions of Microsoft Dynamics AX.

ý Hesitate just accepting when two models have conflicts. Instead consider whether the conflicting model could be coded differently following the guidelines in this paper. Resolved conflicts need special handling during the next upgrade, while “no-conflicts” require no upgrade at all.

þ Do use /conflict:push when elements do collide during import in order to manually handle conflicts as was the practice in Microsoft Dynamics AX 2009.

þ Do handle one conflict model at a time. If a conflict exists and a conflict model is created, solve and determine a strategy for it. Then install the next model.

Moving from staging to production environments

Minimal production downtime is most often a key requirement. Consider the following best practices when moving from a staging environment to a production environment.

þ Do restore a backup of the production database as a staging database. This facilitates this process for minimized downtime.

þ Do install any models required in the staging database, from lower layer to upper layers.

þ Do complete all checklists available, including steps such as compilation, IL generation, and database synchronization.

þ Do complete final testing in staging-environment using production data.

þ Do export the full staging model store by using the EXPORTSTORE command. This command exports all metadata, compiled artifacts, and security data:

AXUtil exportstore /file:MyModelStore /db:myDB_Staging

þ Do prepare the running production system by creating a temporary model schema and import the model data into that:

AXUtil schema /schemaname:NewModel /db:myDB_Prod
AXUtil importstore /file:MyModelStore /schemaname:NewModel /db:myDB_Prod

ý Do not use parameter /idconflict: overwrite to ignore errors about mismatching IDs unless you are more than certain that it is acceptable. Overwriting IDs may corrupt application data.

þ Do stop the AOS and apply the new set of metadata. Apply effectively replaces the existing model store by the newly imported content. You can optionally back up the “old” model store during the process. The apply process typically completes within seconds:

AXUtil importstore /apply:NewModel /db:myDB_Prod /verbose

þ Do start the AOS and follow general guidelines, for example, synchronize the database.

ý Do not waste precious downtime by compiling the application again, because the compiled code is part of what IMPORTSTORE imported.

ý Do not make last minute code changes in the production environment

Glossary of terms

Term / Definition
model / The core of this feature set is a model. A model is a set of model elements in a given layer. Each layer consists of one or more models, of which one is a system-generated model. Any one element in a layer belongs to exactly one model, that is, no element can belong to two different models nor can it belong to no models.
model file / A model file is a file artifact to which models can be exported. Model files have an .axmodel file extension. Model files can be seen as the replacement of AOD files as installation artifacts, while models in the SQL-based model store are the replacement of AOD files used at runtime, that is, when the user runs the Microsoft Dynamics AX application.
axutil.exe / The model management command-line utility. To view an extensive parameter description, type the following:
axutil /?
model management Windows PowerShell cmdlet / The Windows PowerShell equivalent of axutil. The cmdlets are automatically loaded by using Administrative tools | Microsoft Dynamics AX 2012 Management Shell. In the shell type the following:
Get-Help AXModel
to get an overview of cmdlets, and help on each cmdlet, for example, Get-AXModel:
Get-Help Get-AXModel

Working with models in Microsoft Dynamics AX 2012