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
2
WORKING WITH MODELS IN MICROSOFT DYNAMICS AX 2012
Overview
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.
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.
3
WORKING WITH MODELS IN MICROSOFT DYNAMICS AX 2012
 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"?>
<ModelManifest SchemaVersion="1.5" ModelFileVersion="7">
<Name>Public Sector</Name>
<DisplayName>PS</DisplayName>
<Description>Public Sector for Dynamics AX.</Description>
<Publisher>Microsoft Corporation</Publisher>
<Signed>false</Signed>
4
WORKING WITH MODELS IN MICROSOFT DYNAMICS AX 2012
<Category>Standard</Category>
<InstallMode>Standard</InstallMode>
<Version>6.0.0.0</Version>
<Layer>SLN</Layer>
</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 sameelement 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.
5
WORKING WITH MODELS IN MICROSOFT DYNAMICS AX 2012
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
6
WORKING WITH MODELS IN MICROSOFT DYNAMICS AX 2012
 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
7
WORKING WITH MODELS IN MICROSOFT DYNAMICS AX 2012
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
8
WORKING WITH MODELS IN MICROSOFT DYNAMICS AX 2012
Microsoft Dynamics is a line of integrated, adaptable business management solutions that enables you and your
people to make business decisions with greater confidence. Microsoft Dynamics works like and with familiar
Microsoft software, automating and streamlining financial, customer relationship and supply chain processes in a
way that helps you drive business success.
U.S. and Canada Toll Free 1-888-477-7989
Worldwide +1-701-281-6500
www.microsoft.com/dynamics
This document is provided “as-is.” Information and views expressed in this document, including URL and other Internet Web site
references, may change without notice. You bear the risk of using it.
Some examples depicted herein are provided for illustration only and are fictitious. No real association or connection is intended or
should be inferred.
This document does not provide you with any legal rights to any intellectual property in any Microsoft product. You may copy and
use this document for your internal, reference purposes. You may modify this document for your internal, reference purposes.
© 2011 Microsoft Corporation. All rights reserved.
Microsoft Dynamics AX 2012 and Windows PowerShell are trademarks of the Microsoft group of companies.
All other trademarks are property of their respective owners.
9
WORKING WITH MODELS IN MICROSOFT DYNAMICS AX 2012