Best Practices for Using Automation with the Microsoft Dynamics NAV Windows Client

With Automation, Windows-based applications, such as Microsoft Office products, expose Automation objects that Dynamics NAV can access and run using an Automation controller in the development environment. Automation objects are always run on the computer running Microsoft Dynamics NAV Windows client.

Because Automation objects expose a COM interface, Automation can affect the performance and security of your solution. This topic provides best practices and recommendations to follow when implementing Automation in the RoleTailored client to help limit potential performance and security issues.

Note

You specify an Automation objects to run on the Microsoft Dynamics NAV Windows client by using the CREATE Function (Automation) in C/AL code of the object that runs the Automation object.

Automation Object Implementation and Support in the Microsoft Dynamics NAV Windows client

Use the following figure and table to help you determine whether the Automation object is supported on the Microsoft Dynamics NAV Windows client based on the Automation object's characteristics.

Microsoft Dynamics NAV automation object overview

Automation object Supported by Microsoft Dynamics NAV Windows client Remarks
Native code Automation objects that use out-of-process Automation servers Yes This includes Microsoft Office Automation Objects. For more information, see Native and Managed Automation Objects.
Automation objects, including OCX types, which do not add user-interface to Dynamics NAV objects Yes
Automation objects, including OCX types, which add user-interface to Dynamics NAV objects No The control can display information and interact with the user in a window of its own.
Automation objects that execute as single-threaded apartments Yes For more information, see Using Multithreaded Apartment Automation Objects.
Automation objects that execute as multithreaded apartments Yes There are performance considerations with multithreaded apartments. For more information, see Using Multithreaded Apartment Automation Objects.
Managed code Automation objects Yes For more information, see Native and Managed Automation Objects.
Native code Automation objects that use in-process Automation servers Yes This includes DLLs, such as MSXML.dll. For more information, see Native and Managed Automation Objects.
Automation objects that stream parameters and are configured to receive events No In the development environment, an Automation variable includes a WithEvents property, but this property does not have any impact and must be set to No.

Using Multithreaded Apartment Automation Objects

Automation objects can be designed to execute as multithreaded apartments (MTA). MTA Automation objects are designed for highly reentrant, stressed environments with high throughput for multiple clients and are most suitable for running an a server. However, you can use an MTA Automation object on with the Microsoft Dynamics NAV Windows client because the .NET Framework manages marshaling between MTA and STA. If you do, you may decrease performance. Some Automation objects are available in both MTA and STA versions, so you can choose STA. For example, see the DOMDocument and FreeThreadedDOMDocument Automation objects of the Microsoft XML Core Services (MSXML2) library. To read more about these objects and implications on performance, see the Microsoft Support Knowledge Base article PRB: MSXML Performance Bottleneck in ShareMutex Under Stress.

Native and Managed Automation Objects

The Microsoft Dynamics NAV Windows client supports Automation objects that are created from either native or managed code. Automation in Dynamics NAV uses the common language runtime (CLR), which allows managed code to call unmanaged and native Automation objects. The CLR generates a runtime-callable wrapper (RCW) proxy that implements all interfaces of the underlying Automation object. Additionally, the CLR has a built-in marshaling layer that maps the types between the native and managed domains.

Data Type Mapping Between C/AL, COM, and CLR

The following table lists the type mappings between C/AL, COM, and the corresponding .NET CLR types.

C/AL type COM type CLR type
Automation VT_DISPATCH System.Object
BigInteger VT_I8 System.Int64
Boolean VT_BOOL System.Boolean
Char VT_BSTR System.Byte
Code VT_BSTR System.String
Date VT_DATE System.DateTime
DateTime VT_DATE System.DateTime
Decimal VT_CY System.Decimal
Decimal VT_R4 System.Single
Decimal VT_R8 System.Double
InStream VT_STREAM System.Object
Integer VT_I2 System.Int16
Integer VT_I4 System.Int32
OCX VT_DISPATCH System.Object
Option VT_I4 System.Int32
OutStream VT_STREAM System.Object
Text VT_BSTR System.String
Time VT_DATE System.DateTime
Variant VT_VARIANT System.Object

Automation objects are late-bound activated, which means that they must implement the IDispatch interface. This allows the reflection API, which represents the classes, interfaces, and objects in the .NET runtime, to invoke members. The RCW recognizes managed Automation objects as being managed objects, and standard CLR reflection invocation takes place. As a result, in-process (DLL) and out-of-process (EXE) Automation behaves identically when the Automation objects are created in a managed language.

Implementing Automation Objects as VAR Parameters

You can implement an automation object as a VAR parameter in a function call, which means that it is called by reference. If an automation method returns IUnknown or IDispatch objects in the parameter list, then you must create the automation variable before it can be used; otherwise, you will get an error at runtime. For example, the following C/AL code creates an automatioObject variable and calls a method that will return an IDispatch object in the created variable..

create(automationObject, true, true);  
somereturnValue := otherObjectReturningIDispatch(automationObject);  
automationObject.CallObjectMember();  

If the automationObject is used without being created first, the following error will appear at runtime:

System.Runtime.InteropServices.COMException (0x80020005): Type mismatch. (Exception from HRESULT: 0x80020005 (DISP_E_TYPEMISMATCH))

Security - User Account for In-Process Automation Objects and OCX Controls

In-process Automation objects and OCX controls always run under the same user account as the Microsoft Dynamics NAV Windows client. This is because in-process Automation objects are hosted by the current running process and inherit the security properties of the active user.

See Also

COM Overview
How to: Create an Automation Controller
Programming Best Practices
Walkthrough: Using Automation to Write a Letter in Microsoft Office Word
Walkthrough: Using Automation to Create a Graph in Microsoft Excel
Security and Protection