Microsoft Dynamic AX 2009 : Working with .NET Business Connector (part 2) - Exception Handling, Accessing Data

4. Exception Handling

.NET Business Connector has a large set of managed exceptions that can be raised at run time. This set of managed exceptions provides improved granularity, and therefore more flexibility, in handling those exceptions. Most notable are several remote procedure call (RPC)–related exceptions, which you can use to control error handling associated with the connectivity between .NET Business Connector and the AOS. As a general rule, .NET Business Connector does not catch unhandled exceptions (such as OutOfMemoryException). This type of exception is simply propagated to the calling application and prevents .NET Business Connector from masking or hiding such unhandled exceptions.

Refer to the Microsoft Dynamics AX 2009 SDK for more information on the data types, managed classes, and managed exceptions referenced in this section.

5. HelloWorld Example

How do you write C# code that uses .NET Business Connector? The simple example that follows (the .NET Business Connector equivalent of “Hello World”) demonstrates logging on to Dynamics AX. To use the following code, you must be able to log on successfully using the Dynamics AX client. Also, .NET Business Connector must be installed from wherever you execute the code. Create a new project in Microsoft Visual Studio. In the New Project dialog box, select Console Application under Visual C#. This creates the project file structure and files, and presents you with a program named Program.cs. Paste the code in the following example between the curly brackets associated with the Main method. In Solution Explorer, right-click References and choose Add Reference. In the Add Reference dialog box, click the Browse tab. Use the file controls to navigate to the Dynamics AX Client\Bin folder. Select Microsoft.Dynamics.BusinessConnectorNet.dll, and then click OK. This makes .NET Business Connector accessible to the C# application. Now you can build and run the solution.

using System;
using Microsoft.Dynamics.BusinessConnectorNet;
namespace Demo
{
    class HelloWorldFromBC
    {
        public static void Main(string[] args)
        {
            using (Axapta ax = new Axapta())
            {
                try
                {
                    ax.Logon(null, null, null, null);

                    Console.WriteLine("Hello World from Business Connector!");
                     Console.ReadKey();
                    // Logoff
                    ax.Logoff();
                }
                catch (Exception e)
                {
                    Console.WriteLine("Exception occurred: " + e.Message);
                }
            }
        }
    }
}

					  

First, you must instantiate the Axapta class to authenticate, using one of the methods within Axapta. You use Logon method to provide authentication. If you don’t provide non-null parameter values, the following values, which you can override as needed, are used:

• Current Windows user

• Default Dynamics AX company for the user

• Default language for the user

• Default active configuration

A message appears on the console, and the Dynamics AX session is terminated using the Logoff method.

6. Accessing Data

To access data in Dynamics AX, you must use the AxaptaRecord class. The following example shows how to retrieve a list of inventory items that are classified as “raw material.”

using System;
using Microsoft.Dynamics.BusinessConnectorNet;

namespace Demo
{
    // ListInvItemRecords
    // Shows how to retrieve and iterate through a list of Dynamics AX records
    class ListInvItemRecords
    {
        public static void Main(string[] args)
        {
            String invItemNameField = "ItemName";
            Object invItemName;
            String invItemIdField = "ItemId";
            Object invItemId;

            using (Axapta ax = new Axapta())
            {
                try
                {
                    // Logon
                    ax.Logon(null, null, null, null);

                    Console.WriteLine("*** List inventory item records");

                    // Instantiate the Dynamics AX record.
                    AxaptaRecord axRecord = ax.CreateAxaptaRecord("InventTable");

                    // Execute a query.
                    axRecord.ExecuteStmt(
                        "select * from %1 where %1.ItemGroupId == 'RawMat'");

                    // Loop through matching Dynamics AX records.
                    while (axRecord.Found)
                    {
                        invItemName = axRecord.get_Field(invItemNameField);
                        invItemId = axRecord.get_Field(invItemIdField);

                        Console.WriteLine(invItemId + "\t" + invItemName);

                        axRecord.Next();
                    }
                    Console.ReadKey();
                    // Logoff
                    ax.Logoff();
                }
                catch (Exception e)
                {
                    Console.WriteLine("Exception occurred: " + e.Message);
                }
            }
        }
    }
}

					  

Here are the important aspects of the code example:

• Variables are declared to store the Dynamics AX record data that is retrieved and to hold the field names used.

• Authentication is the same as in the HelloWorld example.

• To begin working with a specific type of Dynamics AX record, you must first instantiate an AxaptaRecord object, and you must provide the name or ID of the record as an argument.

• A query is executed against the Dynamics AX record using ExecuteStmt, which parses the query syntax and replaces the substitution variable (%1) with the name of the record. The query syntax is generic. Dynamics AX executes the query with the exact syntax appropriate for the database being used, whether Microsoft SQL Server or Oracle.

• A while loop cycles through the records returned from Dynamics AX, which uses another method, Found, on AxaptaRecord to determine that matching records exist.

• For each record, get_Field retrieves each field value and assigns a value to the appropriate variable declared earlier.

• To proceed to the next record, the Next method is called.

• Logoff is called to terminate the session.