note: if the local version of the file is already up to date, “get latest” does not load the...

Change management and deployment of Microsoft Dynamics AX 2012 modelsRobert BadawySenior Program ManagerMicrosoft Corporation

BRK310-R1

Disclaimer© 2012 Microsoft Corporation. All rights reserved. Microsoft, Windows, Windows Vista and other product names are or may be registered trademarks and/or trademarks in the U.S. and/or other countries. Other names and brands may be claimed as the property of others.

Microsoft Dynamics AX 2012 R2 is a pre-release product under development. The information herein is for informational purposes only and represents the current view of Microsoft Corporation as of the date of this presentation. Because Microsoft must respond to changing market conditions, it should not be interpreted to be a commitment on the part of Microsoft. Microsoft cannot guarantee the accuracy of any information provided after the date of this presentation. All product release dates and features specified are preliminary based on current expectations, and are subject to change without notice. Microsoft may make changes to specifications and product descriptions at any time, without notice.

Sample code included in this presentation is made available AS IS. THE ENTIRE RISK OF THE USE OR THE RESULTS FROM THE USE OF THIS CODE REMAINS WITH THE USER.

MICROSOFT MAKES NO WARRANTIES, EXPRESS, IMPLIED OR STATUTORY, AS TO THE INFORMATION IN THIS PRESENTATION. NO LICENSE, EXPRESS OR IMPLIED, BY ESTOPPEL OR OTHERWISE, TO ANY INTELLECTUAL PROPERTY RIGHTS IS GRANTED BY THIS PRESENTATION. Microsoft products are not intended for use in medical, life saving, or life sustaining applications.

Session Focus

Manage changes in a multiple developer AX

project

Create AX buildsDeploy AX

customizations

Deploy AX on staging and production systems

Best practices, illustrations, recommendations

DeploymentChange management

TFS integration, AX builds, models and model stores

Challenges

Assumptions

This Session Assumes the Following Audience is familiar with Microsoft

Dynamics AX Development, like the AOT, AX elements, and layers

Audience is familiar with source control and TFS

Audience is familiar with AX Models (Import/Export/Model files)

Audience is familiar with AX Model Store

Private AOS Topology with TFS• A private AOS topology is a setup where each developer has his or her own

Microsoft Dynamics AX client, AOS instance, model database, and business database.

• It is the recommended topology.• Artifacts are synchronized between developers using a supported version control

system:• Microsoft Visual SourceSafe, Microsoft MorphX VCS, Microsoft Team Foundation

Server (TFS)• This presentation will focus on TFS.

Shared AOS Topology• A shared AOS topology is a setup where all developers are sharing a common

AOS instance, model database, and business database.• It is supported but not recommended (see coming slide)

Development Topologies

Private AOS with TFS Topology

Shared AOS TopologyNot recommended, this session will focus on the private topology.

Potential issues:• Stale metadata or unpredictable

behavior on clients• Problems installing new solutions or

upgrading existing solutions, which may lead to corrupt data

• Unresponsive AOS while another user is debugging CIL code

• The need to frequently restart the AOS instance

When using this topology, we recommend you use MorphX version control system (VCS)For more details, refer to the white paper: http://technet.microsoft.com/en-us/library/hh352230.aspx

Development Lifecycle Flowchart

Administrator: Setup TFS

Administrator: Configure Version

Control for AX Development (Build

Computer)

Administrator: Add Model (s) to Version

Control (Build Computer)

Administrator: Apply a Label to Latest

Version of Source Files

Administrator: Create AX Build

(Build Computer)

Periodic

Developer: Deploy Build

As needed

Developer: Check out, Check in and

Get Latest

Need new clean build?Yes

Developer: Synchronize to

Latest

No

Developer: Configure Version

Control on Developer Computer

Creating AX Builds

Create an AX Build on Build Computer An AX Build is created from a collection of source files in the central TFS

repository (XPO files, VS Projects, label files). File versions corresponding to a particular build all share a common “label”.

Source files that share a common label constitute a specific version of an AX model or application.

Any Developer should be able to deploy a specific AX build or synchronize their AX environment to that build.

It is recommended to dedicate a one-box installation of AX to be a build computer, where an administrator creates daily/periodic builds of the AX application.

Creating AX Builds: Core Steps (1)1. Sync your local repository files to the latest version of your

model(s) files• Use Team Explorer or use the TFS get command

2. Set the build label (Take a snapshot of your files)• Example: tf label “1.0.0.101” c:\<ProjectName>\

PrimaryAXApplication\ModelA /recursive 3. Stop the AOS4. Delete the current version of your models5. Start the AOS6. Synchronize the business database• ax32.exe startupcmd=synchronize

7. Stop the AOS8. Create new blank models

Creating AX Builds: Core Steps (2)9. Generate the combined import XPO artifact from the individual XPOs

(Use the tool combineXPOs.exe)10. Start the AOS11. Load Label (.ald) files into AX when applicable

ax32.exe -startupcmd=aldimport_<label_file>12. Load combined XPOs into AX using ax32.exe

ax32.exe -aol=%LAYER% -development -model=@model.xml -startupcmd=autorun_Import.xml

13. Review compile errors in import log %USERPROFILE%\Microsoft\Dynamics Ax\Log\allimport.log

14.Build and import AX Visual Studio projects (using MSbuild) when applicable

15.Compile the application, including CIL compilation16.Run database synchronization (DB sync), as above17.Export your model(s) to a model file(s).

AOT context menu > Check-out

Using TFS Integration Features(1)

Check out corresponding XPO

file in local TFS repository for

editing

Enable the element for editing in AX

developer workspace

Start End

AOT context menu > Check-in

Export element to corresponding XPO

file in local TFS repository

Check-in XPO file to TFS central repository

Disable editing of element in AX

developer workspace

Start End

AOT context menu > Get-latest

Using TFS Integration Features(2)

Synchronize corresponding XPO

file in local TFS respository

New version exist in central TFS repository?

Update local XPO file with new version

and load in AXYes

End

No

EndStart

Note: If the local version of the file is already up to date, “get latest” does not load the file into Microsoft Dynamics AX. Microsoft Dynamics AX and the local TFS repository should always be in sync. If you have synchronized the XPO file from outside the Microsoft Dynamics AX environment (by using Team Explorer or another tool), you must manually load the XPO into Microsoft Dynamics AX.

Version Control > Synchronize

Using TFS Integration Features(3)

Synchronize all out-of-date files in the

local TFS repository folder of the

selected model

Combine all updated files in a common

XPO (Files that were not

updated are not included in the XPO)

Start

Load and compile combined XPO

Update synchronize log

End

Version Control > Synchronize Considerations• Errors may occur when you use Version Control > Synchronize depending on the scale

and state of the source repository at the moment of synchronization

Errors may put your system in a state where you are blocked from checking files out of TFS or checking them in to TFS.

If you cannot use TFS features from the Microsoft Dynamics AX development workspace after a synchronize error, delete the contents of the Microsoft Dynamics AX SysVersionControlSynchronizeLog table to recover from this condition.

• If a file’s version in the local repository folder is already equal to the latest version in the TFS central repository (that is, it does not need to be updated), that file is not loaded into Microsoft Dynamics AX when you synchronize (unless you use the “force” option)

Using TFS Integration Features(4)

Change management and TFS integration for multi-developer projects (white paper)• This white paper describes in details tasks and best practices that are related to

development life cycle management in Microsoft Dynamics AX 2012

• It focuses on TFS integration, creation of AX builds, and deployment on development environments.

• It has been released on information source and can be downloaded from here.

Windows PowerShell® (PS) Scripts• PS scripts that create and deploy AX builds have been released and are located in

the Windows PowerShell gallery.• Scripts can handle multiple models, multiple layers, and dependencies on external

models and assemblies

Development Lifecycle: More Details?

Typical Application Lifecycle Flowchart Development

EnvironmentsTest Staging

Production Env .

Develop AX solutions/customizations

Deploy, test, Make changes

Initialize from production, deploy, test, prepare for

production

Export Model

Deploy, operate

Export model store, configuration

Re-base staging env.

Disk repository of released AX

models

Create Builds

Apply changes back

Some Background: Element IDs (1)

Model Store

Business Data

AX Element MetadataAX Element ID 1

Origin GUID Legacy ID

DataID1

• AX elements (Metadata) are associated with corresponding business data based on their element ID.

• Element IDs are specific to each installation and are sometimes referred to as installation-specific IDs.

• When two AX environments share copies of the same business data (Such as transaction, configuration or master data), these environments need to also share the same element IDs

How element IDs are assignedDuring import of model files and XPO files, element IDs are assigned based on 4 rules in the following order:

• If an element already exists that has the same Origin value as the imported element, replace the existing element and reuse its element ID.

• Otherwise, if an element already exists that has the same Type, Name, and ParentID value as the imported element, replace the existing element and reuse its ID.

• Otherwise, if the imported element has a LegacyID value > 0, and the same LegacyID value is available on the target system, then set the element ID to be equal to LegacyID.

• Else, assign a new installation-specific ID from a guaranteed free range that does not collide with any LegacyID values

Some Background: Element IDs (2)

Some Background: Artifact Types XPO files Model files Model store files

Installation tool AX development workspace (MorphX)

AXUtil.exe or Windows PowerShell cmdlets

AXUtil.exe or Windows PowerShell cmdlets

The files can be signed?

No Yes No

Element IDs are preserved on target model store?

All elements that already exist in the model store preserve their IDs (XPO files don’t contain IDs). For new elements, new IDs are generated. 

All elements that already exist in the model store preserve their IDs. For new elements, new IDs are generated.

All element IDs on target system become equal to IDs store in the model store file.

Compilation is required after installation?

Yes Yes No

CIL generation is required after installation?

Yes Yes No

Deploy Models on

a Test Environm

ent

Publish to Servers (when applicable)

Deploy and Compile

Prepare Environment for Deployment

Drain users, reject new

clients

Close active sessions

Stop all AOSinstances

Create Role Centers from

AOT

Publish Enterprise

Portal content

Publish reports

Publish cubes

Delete Current

Version of Models

Start single AOS

Synchronize database

Stop the AOSImport Models

Start single AOS

Compile the application, including CIL

Synchronize database

Start

End

Start all AOS instances

Initialize Staging Environment from Production System

Initialize Staging Environment from Production

Export model store of staging

system to backup file

Export model store of

production system

Import model store file

from previous step

on staging system

Start AOS on staging System

Synchronize database on

staging system

Stop AOS on Staging System

Start

End

Do Not Delete Models on the Staging System!• Same procedure used for deploying models on a test environments

• One important exception: Skip the step where you delete the current version of your models in order to maintain common element IDs with the production system.

Deploy Models on a Staging Environment

Prepare the Staging System for Production

Export metadata and configuration data on staging system

Export workflows

Export integration points data

Export model storeStart End

Deploy on the

Production

Environment

Finalize Deployment

Publish to Servers (when applicable)

Deploy Metadata

Prepare Environment for Deployment

Drain users, reject new

clients

Close active sessions

Stop all AOSinstances

Create Role Centers from

AOT

Publish Enterprise

Portal content

Publish cubes

Clean up old model

schema (if applicable)

Accept new clients on

AOS

Start all AOSinstances

EndImport model store

Start single AOS

Start AX client

Synchronize database

Start

Import configuration data (when applicable)

Import integration

ports

Import workflows

Publish reports

Import model store with minimal downtime Run the schema command to create a new schema.

AXUtil schema /schemaname:%NewSchema% /db:%TargetDatabase%

Import the model store into the temporary schema.

AXUtil importstore /file:%AxModelStoreFile% /schemaname:%NewSchema% /db:%TargetDatabase%

When all users are out of the system, stop the AOS instance

Apply the changes to the model store to move from the temporary schema to the dbo schema.

AXUtil importstore /apply:%NewSchema% /db:%TargetDatabase% /verbose

Deploy on the Production Environment

Production and staging model stores can lose element ID commonality:• Model store files cannot be used to deploy metadata when the source and target system

don’t have common element IDs.

• Even if the staging environment was originally based on the model store of the production system, some scenarios may lead to loss of element IDs commonality, examples are:

Importing new elements (using XPOs or model file) or creating new elements on the production system

Deletion and reinstallation of models. This will regenerate new element IDs.

Installation of a model store on the staging environment from a different source than the original model store.

• You will then need to re-based the staging system from the production model store as described next.

Re-base Staging System from Production

Re-base Staging System

from Production

Publish to Servers (Staging)

Re-base Staging Metadata from Production

Prepare Staging System

Drain users, reject new

clients

Close active sessions

Stop all AOSinstances

Create Role Centers from

AOT

Publish Enterprise

Portal content

Publish reports

Publish cubes

Staging: Export your model(s) to model file(s) **

Production system:

Export model store

Staging: Import model store file from previous step

Staging: Import model files from first

step

Staging: Start the AOS

Staging: Compile the application, including CIL

Staging: Synchronize

database

Start

End

Staging: Start all AOS

instances

Deploying Customizations Across Microsoft Dynamics AX 2012 Environments (White paper)• This white paper covers in details the recommend deployment procedure of metadata

across different AX environments.

• It can be downloaded from here.

• A new version of the paper has been uploaded on October 19, 2012.

Deployment of Metadata: More Details?

Related SessionsEarlier Today (Tuesday) BRK305, Setup, Manageability & Deployment of Dynamics AX 2012, 13:15 – 14:30 BRK304, Inside the Microsoft Dynamics AX 2012 User Interface for Developers, 10:30 –

11:45

Wednesday BRK315, Pushing the envelope of Business Application Development in Dynamics AX BRK307, Implementing a Business Intelligence solution with Dynamics AX 2012 R2 BRK306, Extending the reach of your Dynamics AX 2012 application with Enterprise Portal BRK321, Dynamics AX 2012 Security - Planning and developing for an implementation

Thursday BRK308, Developing cool new Visualizations and powerful Reports with Dynamics AX 2012

R2 BRK314, Integration Dynamics AX with other Line of Business Applications

Links

CombineXpos tool http://informationsource.dynamics.com//

RFPServicesOnline/Rfpservicesonline.aspx?ToolDocName=Microsoft+Dynamics+AX+2012+Combine+XPO+Tool+Beta+1.0%7cQJ4JEM76642V-8-1002

Deploying Customizations Across Microsoft Dynamics AX 2012 Environments (White paper) http://technet.microsoft.com/en-us/library/hh292604.aspx

Change management and TFS integration for multi-developer projects (white paper) http://technet.microsoft.com/EN-US/library/jj713631.aspx

© 2012 Microsoft Corporation. All rights reserved. Microsoft, Windows, and other product names are or may be registered trademarks and/or trademarks in the U.S. and/or other countries.The information herein is for informational purposes only and represents the current view of Microsoft Corporation as of the date of this presentation. Because Microsoft must respond to changing market conditions, it should not be interpreted to be a commitment on the part of Microsoft, and Microsoft cannot guarantee the accuracy of any information provided after the date of this presentation. MICROSOFT MAKES NO WARRANTIES, EXPRESS, IMPLIED OR STATUTORY, AS TO THE INFORMATION IN THIS PRESENTATION.