Using the Call Context

  • Article

Important

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

Call context values are exposed by all Microsoft Dynamics AX services to enable service clients to pass context information specific to Microsoft Dynamics AX. The call context values contain information that is used in the execution of the service call such as a unique message ID and the Microsoft Dynamics AX user and company. These values are sent with Application Integration Framework (AIF) messages as part of the message header.

If you do not specify any values for the call context, the system generates defaults. To use the default values for the call context, you can pass null for the first parameter of the call to the method that calls the service operation, or you can leave the tags out of the message header.

Warning

The data contract for the call context is not published as part of the Web Service Description Language (WSDL) files for the query service and the metadata service. If you want to set any call context values for these services, you must create the code to set the values for the system service call.

Note

This topic has been updated to include information about features that were added or changed for Microsoft Dynamics AX 2012 R2.

CallContext Properties

The following table lists the CallContext properties and their values. All of the properties have default values. That is, if you do not specifically set the CallContext properties when you call a service operation, the default values are used.

Property

Value

Message ID

This is the GUID that uniquely identifies each document.

If you do not specify a message ID, the system generates one. However, if you want to identify a particular message for debugging, you must specify the message ID as part of the call context.

For information about how to use the message ID to check for duplicate messages, see How to: Enable Checking for Duplicate Messages.

LogonAsUser

This is the Microsoft Dynamics AX user who performs the service operation. It uses the submitting user (calling user) in the format “domain\user.”

If LogonAsUser is not specified then the user who makes the service operation call is used. The default user depends on the adapter that is selected. For example, when you use the file system adapter the default user is the owner of the folder where the file resides.

Important

This user must have sufficient permissions in Microsoft Dynamics AX to perform the requested operation. There are significant security considerations for this parameter. For more information, see Services and AIF security and protection.

Company

This is the Microsoft Dynamics AX company for the data on which the service operation is performed.

If Company is not specified then the calling user’s default company is used.

Language

This is the Microsoft Dynamics AX LanguageID for the language that is used to display messages.

The default value for Language is “en-us.”

Partition Key

This value identifies the partition that contains data that is referenced by the service operation.

The default value for PartitionKey is the default partition set for the calling user.

For more information about data partitions, see Data partitioning architecture.

This option is available only if Microsoft Dynamics AX 2012 R2 is installed.

Using the Call Context Values in a Synchronous Call

For any document service or custom service, you must create an integration port to expose the service operation. For synchronous exchanges that use the NetTcp or Http adapters, you add the service reference to the external client project at design time by using the WSDL URI on the Inbound ports form.

Setting the Call Context Values

In the following example, you must first complete the following steps:

  1. Create an inbound port that uses the NetTcp adapter. For more information, see Create, edit, or delete an enhanced integration port.

  2. Expose the create operation for the Sales Order Service as SalesSalesOrderService.create. For more information, see Customize service contracts.

  3. Add the service reference for the Sales Order Service to a project in Visual Studio using the WSDL URI that is created when you activate the port. For more information, see Consuming Microsoft Dynamics AX Services from an External Client.

The following code example illustrates setting the call context values in C# in preparation for calling the create method on the sales order document service.


// Create an instance of the SalesOrderServiceClient.
            SalesOrderServiceClient proxy = new SalesOrderServiceClient();

// Create an instance of the CallContext class.
CallContext context = new CallContext();

// Set the value for Company.
context.Company = "dat";

// Set the value for LogonAsUser.
context.LogonAsUser = "yourdomain\userid";

// Set the value for language.
context.Language = "en-us";

 //Create an instance of the document class AxdSalesOrder.

            AxdSalesOrder salesOrder = new AxdSalesOrder();

The following example continues the example above and illustrates a call to the create method to create a sales order using the Sales Order Service. The code for setting the individual values in the sales order has been omitted.

// Call the create method on the service and pass the CallContext and
// the initialized sales order document. 

EntityKey[] returnedSalesOrderEntityKey = proxy.create(context, salesOrder);

Using the Call Context Values in the Message Header

The following XML illustrates the call context values in the AIF message header.

<Header>
    <MessageId>MessageId1</MessageId>
    <LogonAsUser>domain\user1</LogonAsUser>
    <PartitionKey>PartitionKey1</PartitionKey>
    <Company>Company1</Company>
    <Action>create</Action>

  </Header>

Note

The <PartitonKey> tag is only available if Microsoft Dynamics AX 2012 R2 is installed.

See also

Consuming Microsoft Dynamics AX Services from an External Client

Walkthrough: Exchanging documents by using the NetTcp adapter

Message Header

Query Service

Metadata Service