What Are X++ Containers?

Containers in X++ are versatile data structures that can store multiple values of different types in a single variable. Unlike arrays or lists that typically store elements of the same type, containers can mix strings, integers, dates, and even record IDs in one collection.

Key characteristics:

• Heterogeneous storage (multiple data types)

• Dynamic sizing (grow and shrink as needed)

• One-based indexing (first element is at position 1)

• Built-in manipulation functions with the "con" prefix

Internal Implementation Details

1. Memory Management: X++ containers use a dynamically allocated memory block that grows as needed. When a container exceeds its current capacity, the runtime allocates a larger block and copies the existing elements.

2. Type Handling: Containers maintain type information for each element. When you retrieve a value with conPeek(), the runtime performs an implicit type conversion if necessary.

3. Serialization Support: Containers can be easily serialized and deserialized, making them ideal for storing in database fields or passing between tiers in the D365 architecture.

4. Value Semantics: Containers use value semantics (not reference semantics), meaning when you assign one container to another, a complete copy is made:

     container c1 = [1, 2, 3];
       container c2 = c1;  // Creates a complete copy
       conPoke(c1, 1, 99); // Only affects c1, not c2
   

   5. AOT Representation: In X++ metadata, containers are represented using the Array type with special handling for heterogeneous contents.

Example : Banking Transaction Batch Processing

//Plz Treat this as Example Code , Not Production Standard

public void processBankTransactions(BankAccountTable _bankAccount)
{
    container transactionBatch;
    container currentTransaction;
    BankTransactionTable bankTrans;

    // Build a batch of pending transactions
    while select * from bankTrans
        where bankTrans.BankAccountId == _bankAccount.RecId &&
              bankTrans.Status == BankTransactionStatus::Pending
    {
        // Store each transaction as a container within our batch container
        currentTransaction = [bankTrans.RecId,          // Transaction ID
                             bankTrans.TransDate,       // Transaction date
                             bankTrans.Amount,          // Amount
                             bankTrans.TransactionType, // Type
                             bankTrans.Reference];      // Reference

        transactionBatch += currentTransaction;
    }

    // Process each transaction in the batch
    for (int i = 1; i <= conLen(transactionBatch); i++)
    {
        currentTransaction = conPeek(transactionBatch, i);

        try
        {
            this.processTransaction(currentTransaction);
            this.updateTransactionStatus(conPeek(currentTransaction, 1), 
                                        BankTransactionStatus::Processed);
        }
        catch (Exception::Error)
        {
            this.updateTransactionStatus(conPeek(currentTransaction, 1),
                                        BankTransactionStatus::Error);
            // Log error details
        }
    }
}

Another Example : Bank Reconciliation Helper

When reconciling bank statements, you often need to temporarily store matches between system records and bank statement lines:

//Plz Treat this as Example Code , Not Production Standard
public container findPotentialMatches(BankStatementLine _statementLine)
{
    container matches;
    container matchDetails;
    LedgerJournalTrans journalTrans;
    BankAccountTrans bankTrans;

    // Look for matches in journal entries
    while select * from journalTrans
        where journalTrans.AccountType == LedgerJournalACType::Bank &&
              journalTrans.Account == _statementLine.BankAccountId &&
              journalTrans.AmountCurDebit == _statementLine.Amount &&
              journalTrans.TransDate == _statementLine.TransactionDate
    {
        matchDetails = ['JournalEntry',             // Match type
                        journalTrans.RecId,         // Record ID
                        journalTrans.Voucher,       // Voucher
                        journalTrans.AmountCurDebit,// Amount
                        journalTrans.TransDate];    // Date

        matches += matchDetails;
    }

    // Look for matches in bank transactions
    while select * from bankTrans
        where bankTrans.BankAccountId == _statementLine.BankAccountId &&
              bankTrans.Amount == _statementLine.Amount &&
              bankTrans.ValueDate == _statementLine.TransactionDate
    {
        matchDetails = ['BankTransaction',         // Match type
                        bankTrans.RecId,           // Record ID
                        bankTrans.Reference,       // Reference
                        bankTrans.Amount,          // Amount
                        bankTrans.ValueDate];      // Date

        matches += matchDetails;
    }

    return matches;
}

Advanced Container Techniques in Banking Applications

Beyond the basic examples, here are some advanced techniques that can take your container usage to the next level in banking applications:

1. Functional Container Operations

You can implement functional programming techniques with containers:

//Plz Treat this as Example Code , Not Production Standard

public container filterContainer(container _source, IdentifierName _predicateFunctionName)
{
    container result;
    DictClass dictClass = new DictClass(0); // Properly initialize with an iterator ID

    for (int i = 1; i <= conLen(_source); i++)
    {
        // Call the predicate function to determine if element should be kept
        if (dictClass.callStatic(_predicateFunctionName, _source, i))
        {
            result += conPeek(_source, i);
        }
    }

    return result;
}

// Example usage for transaction filtering
public static boolean isHighValueTransaction(container _transactions, int _index)
{
    container transaction = conPeek(_transactions, _index);
    real amount = conPeek(transaction, 3);

    return amount > 10000; // Consider transactions over 10,000 as high-value
}

// Usage in code
container highValueTransactions = filterContainer(transactionBatch, 
                                                 identifierStr(isHighValueTransaction));

Performance Analysis: Big O for X++ Containers

Understanding the time complexity of container operations is crucial when working with large datasets in banking applications. Here's a comprehensive analysis of X++ container operations:

\Note: While appending is O(1) amortized, individual operations may occasionally trigger a reallocation, which is O(n).*

Search Operations

Modification Operations

Memory Complexity

Memory usage is another critical aspect when dealing with financial data:

Large Dataset Considerations

For very large datasets (e.g., processing thousands of bank transactions), consider these optimizations:

• Batch size control: Limit container sizes to avoid memory issues

• Database filtering: Filter data at the database level before adding to containers

• Selective storage: Store only necessary fields in containers

• Memory management: Clear containers when no longer needed:

  container myContainer; // ... operations ... myContainer = []; // Clear container

  Comparison with Other X++ Collections

  

Best Practices for X++ Containers

1. Document container structure: Always document what each position in your container represents.

2. Consider type safety: For complex scenarios, weigh containers against structured types like classes.

3. Use constants for indexes: Define constants for container positions to avoid "magic numbers":
   #define.CUST_PROFILE_ACCOUNT(1)
#define.CUST_PROFILE_NAME(2)
#define.CUST_PROFILE_BANK_ACCOUNT(3)
// Usage:
str accountNum = conPeek(profile, #CUST_PROFILE_ACCOUNT);

4. Validate containers: Check container length before accessing elements.

5. Nested containers: For complex data, consider containers within containers as seen in the transaction example.

6. Performance monitoring: For large banking operations, monitor memory consumption and processing time when using large containers.

7. Boundary checking: Always check container boundaries before accessing elements:
   if (conLen(container) >= index) { value = conPeek(container, index); }

8. Container reuse: Consider clearing and reusing containers for repetitive operations to reduce memory allocations:
   container reusableContainer;

   // In a loop reusableContainer = []; // Clear before reuse // Add new data...

9. Encapsulate container operations: Create utility methods for common container operations to improve code readability and maintainability.

10. Balance with other data structures: Use the right tool for the job—containers for heterogeneous collections, Lists for homogeneous collections with frequent insertions, Maps for key-value lookups.

Conclusion

X++ containers provide a flexible and powerful way to handle diverse data types in Dynamics 365 F&O banking modules. They shine in scenarios involving temporary storage, parameter passing, and working with heterogeneous data. While they shouldn't replace proper class design for complex business objects, they offer an elegant solution for many everyday development challenges.

Remember that containers are a tool in your arsenal—not a silver bullet. When used appropriately, they can significantly improve code readability and maintainability while maintaining good performance. But they should be complemented with proper object-oriented design for complex domain models and data structures.

As someone who just recently started in the Dynamics 365 F&O space after spending many years in the world of .NET APIs and Web development, my first encounter with X++ felt like landing on an alien planet. The syntax looked almost familiar -- yes, there were curly braces and semicolons -- but the way data structures worked? That was a whole different story.

“Where is the List equivalent in this language?" I remember asking during my first week. "How is it possible to mix different data types in the same collection without type constraints?

If you're a C# developer who's been thrown into the X++ world (or just starting like me), I understand your confusion. This post is everything I wish someone had told me when I first made the transition, written while the struggles and discoveries are still fresh in my mind.

Understanding the X++ Data Access Architecture

When working with Dynamics 365 F&O, you're dealing with a layered architecture designed specifically for enterprise resource planning (ERP) systems. Unlike the web APIs I was used to building, X++ code operates within the Application Object Server (AOS), which mediates between the user interface and the database.

Here's the full picture of how it all fits together:

Try This Now: Explore Your Environment

If you're new to D365 F&O, take a moment to orient yourself:

1. Open Visual Studio with your D365 F&O development environment

2. Navigate to AOT > Jobs

3. Create a new job called "ExploreDataStructures"

4. Add this simple code to print out the type of architecture you're working with

5.        static void ExploreDataStructures(Args _args)
          {
              info("I'm running in: " + Microsoft.Dynamics.AX.Metadata.Core.xppObject.getApplicationContext().getEnvironment());
              info("Available to me are various X++ data structures!");
          }
   

   This simple exercise helps establish where your code will execute and reinforces that you're in a different world than typical C# applications.

X++ Data Structures: The Building Blocks

Try This Now: Your First X++ Container

X++ container with mixed types container myContainer = ['String value', 123, true];

static void ContainerExperiment(Args _args)
{
    container myFirstContainer = ['Customer', 1001, true];

    // Access elements (notice the 1-based indexing!)
    info(conPeek(myFirstContainer, 1)); // Prints "Customer"

    // Add a new element
    myFirstContainer += "New Value";
    (conLen(myFirstContainer)); // Prints 4

    // What happens if we try to mix operations?
    // Uncomment to see the error:
    // int result = conPeek(myFirstContainer, 1) + conPeek(myFirstContainer, 2);
}

What happened when you ran this? Did you notice how X++ handles the mixed types?

A Bit More Concrete Scenario

//Simplified Example Treat them as Mental Models,In Prod there are various Other considerations to be made


// Prepares reconciliation parameters for a bank statement import
static void SetupBankReconciliationParameters(Args _args)
{
    // Container holding mixed types for reconciliation settings
    // [AccountID, ToleranceAmount, AutoMatchEnabled, MatchingPeriodDays]
    container reconcParams;
    str bankAccountId = 'MAIN001';

    // Create container with different parameter types
    reconcParams = [
        bankAccountId,          // String: Bank account ID
        10.00,                  // Real: Tolerance amount for matching
        true,                   // Boolean: Enable automatic matching
        30                      // Integer: Days to look back for matching
    ];

    // Display the parameters
    info("Bank Reconciliation Parameters:");
    info(strFmt("Account: %1", conPeek(reconcParams, 1)));
    info(strFmt("Tolerance Amount: $%1", conPeek(reconcParams, 2)));
    info(strFmt("Auto-Matching: %1", conPeek(reconcParams, 3) ? "Enabled" : "Disabled"));
    info(strFmt("Matching Period: %1 days", conPeek(reconcParams, 4)));

    // Pass parameters to the reconciliation process
    if (conPeek(reconcParams, 3)) // If auto-matching is enabled
    {
        info("Starting automatic reconciliation process...");
        runBankReconciliation(reconcParams);
    }
}

/// Simulates running the bank reconciliation process

static void runBankReconciliation(container _params)
{
    // In a real system, this would use the parameters to
    // perform reconciliation between bank statements and ledger
    info(strFmt("Reconciling account %1 with $%2 tolerance for the past %3 days",
        conPeek(_params, 1),
        conPeek(_params, 2),
        conPeek(_params, 4)));
}

/X++ List List myList = new List(Types::String); myList.addEnd("First item"); myList.addEnd("Second item");

Try This Now: Working with Lists

static void ListExperiment(Args _args)
{
    List nameList = new List(Types::String);
    nameList.addEnd("Alice");
    nameList.addEnd("Dyamics");
    nameList.addEnd("FnO");

    // Lists have iterators
    ListIterator iterator = new ListIterator(nameList);

    while (iterator.more())
    {
        info(iterator.value());
        iterator.next();
    }
}

A Bit More Concrete Scenario

//Simplified Example Treat them as Mental Models,In Prod there are various Other considerations to be made


//Generates a list of bank accounts requiring review based on last activity date
static void FindInactiveBankAccounts(Args _args)
{
    BankAccountTable bankAccount;
    List accountsToReview = new List(Types::Record);
    ListIterator iterator;
    date reviewThreshold = systemDateGet() - 90; // Accounts inactive for 90+ days

    // Find accounts with no recent activity
    while select bankAccount
        where bankAccount.LastActivity < reviewThreshold &&
              bankAccount.AccountStatus == BankAccountStatus::Active
    {
        // Add accounts requiring review to our list
        accountsToReview.addEnd(bankAccount);
    }

    // Process the list of accounts needing review
    info(strFmt("Found %1 bank accounts requiring review", accountsToReview.elements()));

    iterator = new ListIterator(accountsToReview);
    while (iterator.more())
    {
        bankAccount = iterator.value();
        info(strFmt("Account %1 (%2) - Last activity: %3", 
                   bankAccount.BankAccountId,
                   bankAccount.Name,
                   bankAccount.LastActivity));
        iterator.next();
    }
}

X++ Map Map customerMap = new Map(Types::String, Types::Integer); customerMap.insert("CUST001", 1001); customerMap.insert("CUST002", 1002);

Building a Customer Map

static void MapExperiment(Args _args)
{
    // Create a map of customer IDs to credit limits
    Map creditLimitMap = new Map(Types::String, Types::Real);

    // Add some customers
    creditLimitMap.insert("CUST001", 5000.00);
    creditLimitMap.insert("CUST002", 10000.00);

    // Look up a credit limit
    print("Credit limit for CUST001: " + 
        any2str(creditLimitMap.lookup("CUST001")));

    // Update a value
    creditLimitMap.insert("CUST001", 7500.00);
    print("New credit limit for CUST001: " + 
        any2str(creditLimitMap.lookup("CUST001")));
}

A Bit More Concrete Scenario

Imagine a Scenario where you want to build a quick in-memory lookup of BankAccountId → CurrentBalance, so you can:

• Quickly retrieve balances for processing,

• Compare multiple accounts,

• Avoid repeated queries to the database.

•   //Simplified Example Treat them as Mental Models,In Prod there are various Other considerations to be made
    static void Map_BankAccountsBalances(Args _args)
    {
        Map bankBalanceMap = new Map(Types::String, Types::Real); // BankAccountId → Balance
        BankAccountTable bankAccount;
        BankAccountTrans bankTrans;
        AmountCur balance;
  
        // 1. Loop through bank accounts
        while select bankAccount
        {
            // 2. Calculate balance (simplified logic: sum of transactions)
            balance = 0;
            while select sum(AmountCur) from bankTrans
                where bankTrans.BankAccountID == bankAccount.BankAccountId
            {
                balance = bankTrans.AmountCur;
            }
  
            // 3. Add to Map
            bankBalanceMap.insert(bankAccount.BankAccountId, balance);
        }
  
        // 4. Iterate and display
        MapEnumerator mapEnum = bankBalanceMap.getEnumerator();
        while (mapEnum.moveNext())
        {
            str bankId = mapEnum.currentKey();
            real bal   = mapEnum.currentValue();
            info(strFmt("Bank Account: %1 | Balance: %2", bankId, bal));
        }
    }
  

• Database-Related Structures

This is where X++ really differs from C# and web development. Instead of ORM frameworks like Entity Framework, X++ provides specialized structures for database operations:

// Sorting customers by name
RecordSortedList sortedCustomers = new RecordSortedList(tableNum(CustTable));
sortedCustomers.addSortField(fieldNum(CustTable, Name), SortOrder::Ascending);

A Bit More Concrete Scenario

//// Inserts multiple bank accounts in bulk for better performance
// A Mental Model for the data structure - 
//In Production code you would want to Optimize for 
    //1.  batch processing to handle larger datasets for timeout handing 
    //2. Err Handling  
    //etc

public static void insertCustomersBulk()
{
    RecordInsertList recordInsertList;
    CustTable        custTable;
    int              i;

    // 1. Create a new RecordInsertList for CustTable
    recordInsertList = new RecordInsertList(tableNum(CustTable));

    // 2. Loop and create multiple new records
    for (i = 1; i <= 5; i++)
    {
        custTable.clear();
        custTable.AccountNum = strFmt("NEWACC%1", i);
        custTable.Name       = strFmt("New Customer %1", i);
        // ... assign other fields as necessary

        // 3. Add the newly populated record to the RecordInsertList
        recordInsertList.add(custTable);
    }

    // 4. Commit (bulk insert) all records to the database
    ttsbegin;
    recordInsertList.insertDatabase();
    ttscommit;
}

Sorting customers by name
RecordSortedList sortedCustomers = new RecordSortedList(tableNum(CustTable)); sortedCustomers.addSortField(fieldNum(CustTable, Name), SortOrder::Ascending);

A Bit More Concrete Scenario : In-Memory Record Sorting

//Simplified Example Treat them as Mental Models,In Prod there are various Other considerations to be made

//Using RecordSortedList with BankAccountTable
static void InMemorySortingExample(Args _args)
{
    // Create a sorted list of bank accounts by name
    RecordSortedList sortedBankAccounts = new RecordSortedList(tableNum(BankAccountTable));
    sortedBankAccounts.addSortField(fieldNum(BankAccountTable, Name), SortOrder::Ascending);

    BankAccountTable bankAccount;
    int count = 0;

    while select bankAccount
    {
        if (count++ >= 10)
            break;

        sortedBankAccounts.add(bankAccount);
    }

    // Now iterate through the sorted bank accounts
    BankAccountTable sortedAcct;
    info("Bank accounts sorted by name:");

    for (int i = 1; i <= sortedBankAccounts.elements(); i++)
    {
        sortedAcct = sortedBankAccounts.getRecord(i);
        info(strFmt("%1. %2", i, sortedAcct.Name));
    }
}

Points to Ponder

X++ vs. C# Side-by-Side: Visual Comparison

To help you visualize the differences, here's a side-by-side comparison of common operations:

Common Pitfalls When Transitioning from C# to X++

Final Thoughts

As I continue learning my way through the X++ landscape, I'm discovering new patterns and practices every day. This post captures my understanding at this point in my journey, and I'll be sharing new insights as I grow more comfortable with Dynamics 365 F&O development.

If you're also new to this world, I'd love to hear about your experiences and discoveries in the comments. And if you're a seasoned X++ developer who spotted something I've misunderstood, I welcome your gentle corrections -- we're all learning together!

Join me next week when I dive deeper into containers and how they compare to the C# collections I used to rely on. Until then, happy coding in whatever syntax life throws your way!

✨Happy Coding!