Change Management And TFS Integration For Multi-Developer Projects

Microsoft Dynamics® AX 2012

Change management and TFS integration for multi-developer projects

White Paper

June 2013

www.microsoft.com/dynamics/ax

Robert Badawy

Send suggestions and comments about this document to . Please include the title with your feedback.

Table of Contents

Overview 3

Private AOS topology with TFS 3

Topology 4

Flow chart 5

Administrator tasks 5

Administrator: Set up TFS 5

Administrator: Configure version control for Microsoft Dynamics AX development (build computer) 6

Administrator: Add models to version control (build computer) 9

Administrator: Create folders for dependent models and dependent binaries 12

Administrator: Apply a label to the latest version of your files 13

Administrator: Create a Microsoft Dynamics AX build (build computer) 13

Developer tasks 19

Microsoft Dynamics AX developer: Configure version control on the developer computer 20

Microsoft Dynamics AX developer: Deploy a build 20

Microsoft Dynamics AX developer: Check out, check in, and get latest 24

Microsoft Dynamics AX developer: Synchronize the model with the latest files 26

Important considerations and known issues 26

Shared AOS topology 27

Topology 28

Guidelines and known issues 28

Links 28

Updates since initial publication 29

Appendix A: Creating and editing label files 30

Create a label file and add a label 30

Check out a label file for editing 32

Add an existing label file to version control 32

Tips 32

Appendix B: Branching 33

Appendix C: Signing Microsoft Dynamics AX models 33

Strong-name signing 33

Authenticode signing 33

Appendix D: User permissions needed to create and deploy builds 34

Run AXUtil grant or Windows PowerShell Grant-AXModelStore 34

To run AXUtil grant 34

To run the Windows PowerShell Grant-AXModelStore cmdlet 35

Appendix E: Sample files 35

Sample model.xml file 35

Sample Import.xml file 35

Sample ImportVSProject.proj file 35

Overview

This document describes development tasks and best practices that are related to application life cycle management in Microsoft Dynamics AX 2012. It focuses on managing metadata changes across Microsoft Dynamics AX installations when multiple developers are working on the same application. It details steps related to creating and deploying Microsoft Dynamics AX builds on computers connected to a central Microsoft Visual Studio Team Foundation Server (TFS) source control system. The document covers two topologies used by Microsoft Dynamics AX developers: private and shared Application Object Server (AOS) topologies.

Note: Changes have been made to this paper after it was initially published. For details, see Updates since initial publication.

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. This development topology is recommended by Microsoft. Artifacts are synchronized between developers by using one of the supported version control systems (VCSs) in Microsoft Dynamics AX, and a solution is produced by creating a “build” of the sources in the VCS. Microsoft Dynamics AX supports integration with the following VCSs: Microsoft Visual SourceSafe, Microsoft MorphX VCS, and TFS. This document covers only TFS.

Topology

Figure 1 shows an example of a private AOS development topology using TFS as a central repository. Each developer has a private installation of Microsoft Dynamics AX (client, AOS instance, business database, and model database) and is connected to TFS via his or her own TFS workspace. A “build computer” is also connected to TFS, and is reserved for creating builds and administering development tasks.

Figure 1 Private AOS topology with TFS version control

A developer computer has the following components installed: the Microsoft Dynamics AX client, TFS Team Explorer, an AOS instance, a Microsoft Dynamics AX model database, and a Microsoft Dynamics AX business database. The AOS instance, model database, and business database can be on a remote computer, provided that they are not shared with any other user. Other Microsoft Dynamics AX components (and non-Microsoft Dynamics AX components) needed for development, such as .Net Business Connector, Microsoft SQL Server Reporting Services (SSRS) reporting, and Visual Studio, can also be present on the developer computer.

A build computer has the same components as a developer computer, but is kept in a clean state and is not used for development. It is used to generate periodic or daily Microsoft Dynamics AX builds, and to administer version control and build settings. A build computer is typically a one-box installation of all Microsoft Dynamics AX components.

Flow chart

The following flow chart shows the flow of administration and development tasks described next. Every task in the flow chart below is described in detail in the following sections.

Figure 2 Administrator and developer tasks

Administrator tasks

Administrator: Set up TFS

After installing Microsoft Dynamics AX, the administrator needs to set up his or her computer to connect to the TFS VCS by completing the following tasks. The links provide technical documentation about how to set up the VCS – specifically, TFS – for Microsoft Dynamics AX development.

1. Install prerequisites.

See How to: Install Prerequisites on the Server that Runs the Team Foundation Server Version Control System.

2. Set up the TFS server (from the administrator’s computer).

See How to: Set up the Server that Runs the Team Foundation Server Version Control System.

3. Set up each developer’s computer for TFS version control.

See How to: Set up Developer Computers for Version Control Using Team Foundation Server.

Administrator: Configure version control for Microsoft Dynamics AX development (build computer)

After the TFS server is set up, the administrator needs to configure Microsoft Dynamics AX for version control using TFS. The example in this section illustrates these steps. This section assumes that the administrator has already installed and configured Microsoft Dynamics AX on his or her computer.

In this example, the administrator is setting up version control for an application named AxApplication1 that includes two models: ModelA and ModelB. This example does not use branching.

1. Create a local application root folder to map to the TFS repository. In this example, create the folder C:\MyTFSProject\AxApplication1.

2. Create the TFS repository structure on the TFS server. You can use Team Explorer to complete these steps.

Create a project named MyTFSProject.
Add and check in the folder named AXApplication1.

Verify before you proceed!
1. You have a TFS central repository structure:
2. The TFS repository is mapped to the local folder:
C:\MyTFSProject\AXApplication1

3. Enable Microsoft Dynamics AX for TFS version control on your computer:

Start the Microsoft Dynamics AX development workspace.

Click Version Control > Version Control Parameters.

In the Version control status field, select Enable.
In the Version control system field, select Team Foundation Server.

Note: Microsoft Dynamics AX can integrate with different version control systems; this document focuses on integration with Team Foundation Server.

In the Repository folder field, enter the path of the root repository folder (in this example, C:\MyTFSProject).
Select environment settings.

Click the Team Foundation Server link.
In the Team Foundation Server URL field, enter the URL of the server that has the TFS team project.
In the Team Foundation project name field, enter the name of the TFS project.
In the Branch folder field, enter the location of the branch folder. You can leave this field blank.
In the Application root folder field, enter the location of the application root folder (in this example, AXApplication1).
Click OK.

4. Configure global version control settings. Click Version Control > System settings to configure global settings for Microsoft Dynamics AX version control: best practices, labels, illegal element names, excluded element types, and models.

These settings are stored in the VCSDef.xml file located under C:\MyTFSProject\Definition. This file is automatically created the first time you configure global settings.

For more information, see How to: Configure Global Version Control System Settings (Administrator).

5. After you have finished configuring global settings, check in the VCSDef.xml file from Version Control > Pending Objects. The settings in this file will be shared by all Microsoft Dynamics AX developers connected to the MyTFSProject project.

Note: Every time an administrator or a developer makes changes to the global version control system settings (Version Control > System settings) and checks in a new VCSdef.xml file, other Microsoft Dynamics AX 2012 developers who are connected to the same TFS application can update their settings by doing either of the following:

· Restart the Microsoft Dynamics AX 2012 Client.

· Reinitialize the Microsoft Dynamics AX 2012 version control parameters. Click Version Control > Version Control Parameters, and then click OK.

Administrator: Add models to version control (build computer)

Use the following steps to add a model to source control. As mentioned in the previous section, this example uses two models, ModelA and ModelB, for illustration purposes.

1. Start the Microsoft Dynamics AX development environment in the desired development layer of the model(s) you are adding to version control.

2. Create ModelA and ModelB, if they do not already exist on your computer.

Note: If you are not familiar with models, see Models and Working with Models in the AOT.

3. Create the local repository model folders. Based on the MyTFSProject example from the previous section, create the following folders in your local repository:

· C:\MyTFSProject \AXApplication1\ModelA

· C:\MyTFSProject \AXApplication1\ModelB

Tip: Because of a known issue, we recommend that you do not use the layer name of your model as part of the repository path. In this example, do not use a folder named usr as a parent folder of ModelA.

4. Click Version Control > Add model to version control.

5. Enter a description.

6. Select ModelA.

7. Enter the local repository folder of ModelA.

8. Click OK.

9. Repeat steps 3 through 8 for ModelB.

Notes:

· The steps performed in the Add model to version control dialog box are required only once per model.

· A model.xml file is created under C:\MyTFSProject\AXApplication1\<ModelName> for every model you add to version control.

· If your model already contains Microsoft Dynamics AX elements, adding a model to the model store also checks in all XPO files associated with the model.

10. Verify that entries for both ModelA and ModelB appear under Version Control > System settings > Models.

11. Check in dummy test elements:

Select ModelA as the current model in the Microsoft Dynamics AX development workspace.

Create a new test class.
Create a new test table.
Right-click each test element, and then select Add to Version Control.
Check in pending objects from Version Control > Pending Objects.

Note: Any changes you make to system settings require that you check in the VCSDef.xml file from Version Control > Pending Objects.

Tip: You can also check in this file directly from Team Explorer.

Verify before your proceed!
1. Your TFS central repository structure contains both model folders:
2. Each model folder contains a model.xml file. The model.xml file contains information about the model, such as the model name, publisher, layer, and display name.
3. The local TFS repository folder also contains both model folders, and each folder contains a model.xml file:
4. The test table and test class exist in the model folders (in both the local folder and TFS server):
· The test class XPO file is under C:\MyTFSProject\AXApplication1\ModelA\Classes.
· The test table XPO file is under C:\temp\MyTFSProject\AXApplication1\ModelA\Data Dictionary\Tables.

Sample VCSDef.xml file with ModelA and ModelB

</BestPractice>

</LabelFile>

</UnwantedObjectNames>

</Models>

</VCSParameters>

Administrator: Create folders for dependent models and dependent binaries

If your application has dependencies on other Microsoft Dynamics AX models (like ISV models) or .Net assemblies and other binaries, we recommend that you create the following folders in TFS to store these dependencies.

· AX models folder: //MyTFSProject/AxApplication1/dependencies/appl

· Dependent binaries folder: //My MyTFSProject/AxApplication1/dependencies/bin

For example, you may be developing models on the VAR layer that depend on third party ISV models and other binaries. Place the ISV models in the appl folder and the binaries in the bin folder.

In this example, AxApplication1 is the name of your application root folder that was setup in the previous section.

This particular folder structure for dependencies is not required, unless you are using the PowerShell scripts to create Microsoft Dynamics AX builds, as described later in this document.

A sample application folder structure in TFS would then look like:

c:\MyTFSProject\AXApplication1\Definition\VCSDef.xml

c:\MyTFSProject\AXApplication1\ModelA\model.xml

c:\MyTFSProject\AXApplication1\ModelA\...

c:\MyTFSProject\AXApplication1\ModelB\model.xml

c:\MyTFSProject\AXApplication1\ModelB\...

c:\MyTFSProject\AXApplication1\dependencies\appl\ISVSolution1.axmodel

c:\MyTFSProject\AXApplication1\dependencies\bin\externalassembly.dll

Administrator: Apply a label to the latest version of your files

As a prerequisite to enabling the creation of Microsoft Dynamics AX builds, the administrator, on a periodic (daily) basis, should apply a label to the latest version of the project files in the TFS central repository. The label is used as the identifier of the daily/periodic build (example label: v1.0.1). The administrator should incrementally change the label every time a new label is applied. The label value should be based on the project milestones.

In TFS, labels let you take a snapshot of your files, so that you can refer back to that snapshot later. By using your label, you can view, build, or even roll back a large set of files to the state they were in when you applied the label.