Walkthrough: Exchanging documents by using the NetTcp adapter


This content is archived and is not being updated. For the latest documentation, see Microsoft Dynamics 365 product documentation. For the latest release plans, see Dynamics 365 and Microsoft Power Platform release plans.

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

The NetTcp adapter provides for synchronous communication by using the Transmission Control Protocol (TCP) transport. This walkthrough demonstrates using an inbound port with the NetTCP adapter to read a sales order from Microsoft Dynamics AX. In this walkthrough, you will create an inbound integration port and then use C# code to create a command-line program that reads a particular sales order.


This walkthrough does not demonstrate how to work with security settings, such as those that restrict an exchange to a particular company or partition. For more information about security settings, see Configure security for integration ports.


  • Microsoft Dynamics AX must contain at least one valid sales order.

  • The sales order service must be registered. For information about how to register services, see Customize service contracts.

  • You must have Microsoft Visual Studio 2010 installed and be familiar with how to create simple Visual C# project.

Create and configure the integration port

When you create an integration port that uses the NetTCP adapter, AIF publishes a network Uniform Resource Identifier (URI) and a Web Services Description Language (WSDL) address. Together, these addresses provide access to the service operations exposed by the port.

  1. Open the Inbound ports form. Click System administration > Setup > Services and Application Integration Framework > Inbound ports.

  2. Click New.

  3. Name the new integration port SalesOrderRead.

  4. In the Adapter list in the Address group, select NetTcp.

  5. On the Service contract customizations FastTab, click Service operations.

  6. In the Select service operations form, select SalesSalesOrderService.read in the Remaining service operations list. Click the left arrow to move the service operation to the Selected service operations list. Then, close the form.

  7. You can modify the document data policy to match the fields that you want to return in the response. If you do not specify a data policy, then all sales order schema elements are included in the response message by AIF. If you specify a data policy but do not modify the default data policy, then only the default elements are included in the sales order schema.

  8. Activate the integration port.

  9. Make note of the address that is displayed in the WSDL URI text box.

  10. Close the Inbound ports form.

Create a NetTcp client application

This section describes how to create a simple client application that synchronously exchanges messages with the integration port. The client application code is written in the C# programming language. The sample application reads a sales order from Microsoft Dynamics AX and then displays the sales order ID and the customer account number.

  1. Open Visual Studio and create a new console application project in Visual C#. Name the project "TCP Client".

  2. In Solution Explorer, right-click the project name and then click Add Service Reference.

    The Add Service Reference dialog box opens.

  3. In the Address text box, enter the WSDL URI from the port that you created in the previous section. For example:

    http:// YOUR_AOS_NAME:8101/DynamicsAx/Services/SalesOrderRead
  4. Click Go. Wait for Visual Studio to find the service.

  5. Click OK to close the dialog box.

  6. Open Program.cs. In the code editor, replace the empty Main function with the following C# code:

    static void Main(string[] args)
        // Create the sales order objects
        // Service client
        ServiceReference1.SalesOrderServiceClient cl = new ServiceReference1.SalesOrderServiceClient();
        // Sales order object to receive response
        TCP_Client.ServiceReference1.AxdSalesOrder resp;
        // Create the entity key list for the request
        ServiceReference1.EntityKey[] readRespKeys = new ServiceReference1.EntityKey[1];
        readRespKeys[0] = new ServiceReference1.EntityKey();
        readRespKeys[0].KeyData = new ServiceReference1.KeyField[1];
        readRespKeys[0].KeyData[0] = new ServiceReference1.KeyField();
        readRespKeys[0].KeyData[0].Field = "SalesId";
        // Ask the user for a sales order ID
        Console.WriteLine("Enter the sales order ID:");
        // Add the result to the entity key value
        readRespKeys[0].KeyData[0].Value = Console.ReadLine();
            // Try to read the sales order
            resp = cl.read(null, readRespKeys);
            // Display the information from the first sales table
            Console.WriteLine("For sales order: " + resp.SalesTable[0].SalesId);
            Console.WriteLine("Customer Account is: " + resp.SalesTable[0].CustAccount);
        catch (Exception e)
            Console.WriteLine("Exception: " + e.Message);
  7. Build the project.

Read a sales order

To read a sales order, run the client application.

  1. In Windows, open a Command Prompt window.

  2. At the command prompt, run the TCP Client application.

  3. When prompted by the application, enter a valid sales order ID.

If the sales order is successfully read, the application displays the sales order ID and the customer account number. Otherwise, the application displays an exception message.

See also

Managing integration ports

Walkthrough: Transforming a document