Walkthrough: Integrate an Application with Microsoft Dynamics AX Using .NET Business Connector

Article
08/03/2018

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

The Microsoft Dynamics AX development environment enables you to integrate a .NET application with Microsoft Dynamics AX. This feature gives developers a way to develop integrations using Microsoft Visual Studio. The ability to integrate Microsoft Dynamics AX with other systems is a common requirement. There are a variety of technologies that you can use to integrate Microsoft Dynamics AX with other applications, which include .NET Business Connector. The following table describes the suggested ways to integrate with Microsoft Dynamics AX in different scenarios.

Technology	Intended Use
.NET Business Connector	Author business logic using a .NET language. For more information, see .NET Business Connector Overview.
Services	Access Microsoft Dynamics AX data and functionality. For more information, see Developing with Services and AIF.
Common language runtime (CLR)	Create and execute managed components from X++ code. For more information, see .NET Interop from X++.

This walkthrough illustrates the following tasks:

Creating a C# Windows project
Adding a reference to .NET Business Connector
Creating the layout for a form
Adding code behind the form
Retrieving a record using a where clause

Prerequisites

To complete this walkthrough, you will need:

Microsoft Dynamics AX with data in the CustTrans table
Microsoft Visual Studio 2010
4.0 .NET Framework

Note

This topic contains steps to use the 4.0 .NET Framework. You can use an earlier version of the .NET Framework but the project target framework setting and application configuration settings need to be updated accordingly.

Creating a C# Windows Project

The first step is to create a Windows application that will access data in Microsoft Dynamics AX.

To create a C# Windows project

Open Visual Studio.
From the File menu, click New, and then click Project to display the New Project dialog box.
In the Installed Templates pane, click Visual C#. In the Templates pane, click Windows Forms Application.
Set the name to DisplayCustTransAccountNum.
To change the location of the solution directory, click Browse, and specify a new location.
Click OK.

Adding a Reference to .NET Business Connector

To access Microsoft Dynamics AX data and functionality, you must create a connection between a .NET application and Microsoft Dynamics AX using .NET Business Connector. In this section, you will add a reference to the .NET Business Connector assembly, update the target framework, and update the application configuration settings. For more information assemblies, see How the Runtime Locates Assemblies.

To add a reference to .NET Business Connector

In Solution Explorer, right-click References, and then click Add Reference.
In the Add Reference window, click the Browse tab.
Specify the location of Microsoft.Dynamics.BusinessConnectorNet.dll, and then click Add.

Note

For a typical install, the assembly is located at C:\Program Files (x86)\Microsoft Dynamics AX\60\Client\Bin\.
Click OK.

To set the project target framework

In Solution Explorer, right-click the DisplayCustTransAccountNum project, and then click Properties.
In the Application tab, set the Target framework to .NET Framework 4.

To update the application configuration settings

In Solution Explorer, double-click the app.config file and update the following configuration settings.
```
<startup useLegacyV2RuntimeActivationPolicy=”true”>
<supportedRuntime version “v4.0” />
```
On the File menu, click Save app.config.

Note

When you build your project, the development environment automatically creates a copy of your app.config file, changes its file name so that it has the same file name as your executable, and then moves the new .config file in the bin directory.

If you do not update the app.config file, you will get the following error:

“Mixed mode assembly is built against version 'v2.0.50727' of the runtime and cannot be loaded in the 4.0 runtime without additional configuration information.”

Creating the Layout of the Form

After you have created DisplayCustTransAccountNum, you can add controls to the form by dragging them from the toolbox.

To create the layout a form

In the toolbox, click the Label control, and then add it to the form.
Click the TextBox control and add it to the form next to the Label.
Click Button and add it to the form next to the TextBox.

Adding Code Behind the Form

In this section, you will add code behind the form to extract the data from Microsoft Dynamics AX. You will use the AxaptaRecord class to execute a query. This query will extract data from Microsoft Dynamics AX. You will retrieve and display customer data on the controls that you have added to the Windows form.

To add code behind the form

On the form, double-click button1 to access the Form1 code.

Add the following code to the button1_Click method.

Microsoft.Dynamics.BusinessConnectorNet.Axapta DynAx = new 
    Microsoft.Dynamics.BusinessConnectorNet.Axapta();
Microsoft.Dynamics.BusinessConnectorNet.AxaptaRecord DynRec;
try
{
    // Authenticate the user and establish a session.
    DynAx.Logon(null, null, null, null);

    // Define the record as the CustTrans table.
    DynRec = DynAx.CreateAxaptaRecord("CustTrans");

    // Define the query that will run on the CustTrans records.
    // This will return all the data in the CustTrans table with 
    // the cursor positioned at the first record in the table.
    DynRec.ExecuteStmt("select * from %1");

    // Check if the query returned any data.
    if(DynRec.Found)
    {
        // Display the record on the form that was retrieved from the query.
        textBox1.Text = (string) DynRec.get_Field("AccountNum");
    }
}
// In a finally block, log the user off.
finally
{
    DynAx.Logoff();
}

Press F5 to run the application.
On the form, click button1. The text box displays the first AccountNum record in your CustTrans table.
Close the form.

Warning

An instance of the Axapta class must not be given to a second thread.

Retrieving a Record Using a Where Clause

In this section, you will modify the code to look for a specific record. You will use a where clause to find a record in your CustTrans table. In the following example you will replace the ' your_search_criteria_here ' with the name of a record in your CustTrans table, for example 1103 .

To retrieve a record using a where clause

On the form, double-click button1 to access the Form1 code.

Declare the following variable.

string fieldAccountNum = ("AccountNum");

Change the execute statement to include a where clause.

DynRec.ExecuteStmt(string.Format("select * from %1 where %1.{0} ==
    'your_search_criteria_here'", fieldAccountNum));

Press F5 to run the application.
On the form, click button1. The text box displays the record for the criteria you supplied, like 1103.

Next Steps

This topic demonstrates how to access data in Microsoft Dynamics AX using .NET Business Connector. Using .NET Business Connector enables information technology (IT) departments and independent software vendors (ISV) to build .NET solutions and integrate them with Microsoft Dynamics AX. For more information, see .NET Business Connector Overview.