Collection Classes in Microsoft Dynamics AX

Applies To: Microsoft Dynamics AX 2012 R3, Microsoft Dynamics AX 2012 R2, Microsoft Dynamics AX 2012 Feature Pack, Microsoft Dynamics AX 2012

The X++ language syntax provides two compound types: arrays and containers. They are useful for aggregating values of simpler types. However, you cannot store objects in arrays or containers. The Microsoft Dynamics AX collection classes have been designed for storing objects. The classes are implemented in C++ to achieve the maximum performance (they are system classes).

Note

Collection classes were formerly called Foundation classes.

Collection Classes

The collection classes are shown in the following table.

Class	Description
Array	Similar to the X++ language array type except that it can hold values of any single type, including objects and records. Objects are accessed in a specific order. For more information, see X++, C# Comparison: Array Syntax.
List	Contains elements that are accessed sequentially. Unlike the Array class, the List class provides an addStart method. As with the Set class, the List class provides methods getEnumerator and getIterator. You can use an iterator to insert and delete items from a List object.
Map	Associates a key value with another value.
Set	Holds values of any single type. Values are not stored in the sequence they are added. Instead, the Set object stores them in a manner that optimizes performance for the in method. When you add a value to a Set object which is already storing that same value, the add attempt is ignored by the Set object. Unlike the Array class, the Set class provides the methods in and remove.
Struct	Can contain values of more than one type. Used to group information about a specific entity.

Types Stored in Collections

The constructor for each collection class, except Struct, takes in a parameter value that is an element of the Types system enum. The collection instance can store items of that type only.

The Types::AnyType enum element is a special case and it cannot be used to construct a usable collection object, such as a Set object.

The null value cannot be stored as an element in a Set object. And null cannot be a key in a Map object.

Do Not Change Elements During Iteration

You can iterate through an X++ collection object with an iterator or enumerator. Here are typical examples of how you can obtain an iterator:

• new MapIterator(myMap)

• myMap.getEnumerator()

For Set objects, if any elements are added or removed after an iterator is created, the iterator instance can no longer be used to read from or step through the collection.

For Map objects, element removals invalidate the iterator just as for Set objects. However in Microsoft Dynamics AX 2012, a MapIterator object remains valid even after a call to the Map.insert method. This is true whether the key is new, or whether the key already exists and only the value is actually being updated in the Map element. X++ code that calls Map.insert and relies on the iterator object remaining valid might fail if run as .NET Framework CIL.

For more information, browse to the MSDN blogs and search for the X++ blog post titled Changes to the Collection Classes in Dynamics AX 2012, or try this direct link to the X++ Blog.

Extend a Collection Class

You can use the collection classes to form more complex classes. For example, a stack might easily be implemented by using a list where the elements are always added to the start of the list. The newest element then occupies the top of the stack.

You can also extend the collection classes. For example, you might extend the List class to create a list of customer records where the operations could be made type safe. The derived collection class would accept only customer records, not just any record.

See also

Composite Data Types

Announcements: New book: "Inside Microsoft Dynamics AX 2012 R3" now available. Get your copy at the MS Press Store.