Inside Dynamics AX 4.0: Working with the .NET Business Connector

[Blog bot]

Источник: http://feeds.feedburner.com/~r/Insid...connector.html
==============

This section takes a closer look at building applications with the .NET Business Connector, including the following topics:

• Data types and mappings
• Managed classes
• Request and response processing
• Exception handling

Data Types and Mappings

The .NET Business Connector makes it easier to develop managed applications that integrate with Dynamics AX by bridging two programming environments: the managed .NET Framework environment and the unmanaged Dynamics AX X++ environment. Inevitably, some form of translation is required when passing objects and data between these two environments. In below maps equivalent data types between .NET and Dynamics AX.

Data Type Mappings

The Business Connector managed class methods explicitly support specific data types for parameters and return values. Refer to the Microsoft Dynamics AX SDK for more information.
Managed Classes
This section provides an overview of the managed classes in the .NET Business Connector. You develop applications with the .NET Business Connector by instantiating and using the public managed classes described in below table.

.NET Business Connector Managed Classes

Examples of how these classes are used in an application are provided in the following sections.
Request and Response Processing
Much like any integration component, the Business Connector processes requests and returns responses associated with the use of the managed classes by applications across all the established Business Connector user sessions.
Request Processing
The diagram shown in below image depicts the processing steps associated with a request made through the managed classes.

1. A request is initiated by invoking a managed class.
2. The request is received and marshaled across the transition layer (where .NET objects and data are converted from .NET to X++).
3. The transition layer dispatches the request to the interpreter in the .NET Business Connector.
4. If the request involves executing X++ code, this code is run either locally or remotely on the AOS, depending on the directive associated with the code.
5. After the request is processed, a response is generated.

Request processing in the .NET Business Connector.

Response Processing
The diagram shown in below image depicts the processing steps associated with generating a response.

1. The active request processed by the .NET Business Connector completes, successfully or unsuccessfully.
2. The response is instantiated and dispatched by the interpreter to the transition layer.
3. The transition layer marshals the response to the managed classes (converting objects and data from X++ to .NET).
4. The response is returned to the caller, which is the application that initially invoked the Business Connector.

Response processing in the .NET Business Connector

The main variation in the request and response cycle is the location where the X++ code being invoked is executed. This is controlled by the declaration associated with the X++ code. By default, the X++ code runs where calledthat is, from the interpreter where it is invoked. If the client keyword is used, this forces execution on either the Business Connector or the Dynamics AX client. If the server keyword is used, the code is executed by the AOS.
Exception Handling
The .NET Business Connector has a large set of managed exceptions that can be raised at run time. Although it was originally based on the errors in the COM Business Connector, this set of managed exceptions has been extended in Dynamics AX 4.0 to provide improved granularity, and therefore more flexibility, in handling those exceptions. Most notable is the addition of several remote procedure call (RPC)related exceptions, which you can use to control error handling associated with the connectivity between the Business Connector and the AOS. As a general rule, unhandled exceptions (such as OutOfMemoryException) are not caught by the Business Connector. This type of exception is simply propagated to the calling application and prevents such unhandled exceptions from being masked or hidden by the Business Connector.
A new exception has been added in Dynamics AX 4.0 that provides a consistent way to manage AOS failures. If the AOS to which the .NET Business Connector currently has affinity becomes inaccessible, a BusinessConnectorInstanceInvalidException exception is raised for every call to a method in the managed classes thereafter. This exception can then be used to take other actions, such as terminating the process so it can be restarted.
Refer to the Microsoft Dynamics AX SDK for more information on the data types, managed classes, and managed exceptions referenced in this section.
HelloWorld Example
How do you write C# code that uses the .NET Business Connector? The simple example that follows (the 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 AX client. Also, the .NET Business Connector must be installed from wherever you will 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 called 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 the .NET Business Connector accessible to the C# application. Now you can build and run the solution.

First, you must instantiate the Axapta class to authenticate, using one of the methods within the Axapta class. Authentication is accomplished by using the Logon() method. If you do not provide any explicit parameter values, the following values, which can be overridden as needed, are used:

• The current Windows user
• The default Dynamics AX company for the user
• The default language for the user
• The default active configuration

A message appears on the console, and the Dynamics AX session is terminated using the Logoff() method.
Accessing Data
To access data in Dynamics AX, you must use the AxaptaRecord class. The following example shows how to retrieve a list of bike-related inventory items that are classified as "raw material."
Here are the important aspects of the code example:

• Variables are declared to store the Dynamics AX record data that you will retrieve 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 of a generic form. Dynamics AX executes the query with the exact syntax appropriate for the database being used, whether it is Microsoft SQL Server or Oracle.
• A while loop cycles through the records returned from Dynamics AX, which uses another method on AxaptaRecord called Found to determine that matching records exist.
• For each record, get_Field() retrieves each of the field values and assigns a value to the appropriate variable declared earlier.
• To proceed to the next record, the Next() method is called.
• The AxaptaRecord object instance is disposed of to release any unmanaged resources associated with it, and Logoff() is called to terminate the session.

You can also invoke X++ business logic directly from the .NET Business Connector, as shown in the following section.


Invoking Business Logic
In addition to accessing data, you can also invoke business logic defined in Dynamics AX directly from the .NET Business Connector. In this example, you call a method in an X++ class to update inventory item details in Dynamics AX based on data from a separate inventory management system. To do this, you use the CallStaticClassMethod method in the Axapta managed class, as shown in this code.
The X++ class returns a Boolean result in this case, which is then used to determine the next action in the application.
As you can see from these examples, developing applications that integrate with Dynamics AX using the .NET Business Connector is relatively straightforward. Although real applications would use the managed classes more extensively, the approach to accessing data and invoking business logic remains the same.
</img> </img> </img> </img> </img>


Источник: http://feeds.feedburner.com/~r/Insid...connector.html