Using an Index File with Dexterity Source Code Control

David MeegoWhile many Dexterity developers are now using Source Code Control (usually with Microsoft Visual Source Safe), there are a number of developers that did not know that an index file should always be used with Source Code Control.

This post explains how Microsoft Dynamics GP developers can use an Index File with Dexterity Source Code Control to ensure that the resources they create keep the same Resource IDs between different builds and versions of code. Examples of these resources include forms, reports, tables, and fields.

Overview 

When you use the Source Code Control functionality built in to Dexterity, all resources are stored in a text representation in your source code repository (usually Microsoft Visual SourceSafe). These resources are stored with their names as the unique identifier.

In your development dictionary, the unique identifier is actually the internal Resource ID generated by Dexterity. For third-party developers (most Dexterity developers are third-party developers), these Resource IDs start at 22,000.

Each resource you add is assigned the next available Resource ID for that resource type. Therefore, your resources are numbered in the order they were created, unless you have deleted some resources, in which case the Resource ID will be reused.

When creating a new build, you make a copy of an unmodified Dynamics.dic from a client installation. Then update all your resources from the repository into this dictionary. During this process, resources are brought in to the dictionary in alphabetical order and are assigned Resource IDs as resources of each type are added.

The fact that your Resource IDs are now ordered alphabetically will cause a number of problems, including the following:

  • Updates to any modified forms or reports that exist for your product will probably fail.
  • Security records indicating that access to one of your forms or reports has been denied will now point to the wrong Resource ID.
  • Security records indicating that access to a modified version of one of your forms or reports has been granted will now point to the wrong Resource ID.

In other words, the alphabetization of Resource IDs can make life difficult.

The solution is the Index File, which tracks the Resource IDs assigned to resources and ensures that they are maintained between each build of your Dexterity project.

Putting the Index File to work

If you have multiple developers working on a single project, you will need to assign one developer as the administrator for the project. The administrator’s role is to create the new builds and work with the Index File. The administrator should perform the following steps on his or her machine:

  1. Go to the Edit menu, select Options, and then select the Source Control tab. Make sure Enable Administrative Features is checked. If you have not created an Index File before, create one now using your current development dictionary. From the Explorer menu, select Source Control, and then select Update Index File. Once created, the Index File can be found in the repository under the Admin folder.
     
  2. Every time a build is completed, select Explorer, Source Control, and then Update Index File. This will create the Index File that will be used for the next build.
     
  3. Every time you create a new build, select Explorer, Source Control, and then Update. On the Update from Repository window, check the Use Index File option. In the words of one Dexterity product manager, "Just because it is an option does not mean it is optional."

Following these steps will ensure that Resource IDs stay consistent between builds and between releases.

For more information, see “Part 9: Source Code Control” in the Programmers Guide, Volume 1 that ships with Dexterity as a PDF document.

This information has previously been available from the following links:

How to use an index file and the Microsoft Dynamics GP Dexterity source code control functionality to make sure that the resources that you create maintain the same resource ID in different builds and versions of your code (KB 894699) Secure Link

How to use an Index File

This Knowledge Base article describes the use of Source Code Control to upgrade a custom Dexterity application:

How to upgrade a Dexterity-based application in Microsoft Dynamics GP or in Microsoft Great Plains by using the Dexterity Source Code Control Service (KB 910527) Secure Link

 

In summary, if you are using Dexterity Source Code Control and not using an index file, please start using one.

David

Ref: KB 894699