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 Microsoft 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.

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 Microsoft Dynamics NAV objects	Yes
Automation objects, including OCX types, which add user-interface to Microsoft 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 Microsoft 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

Tasks

How to: Create an Automation Controller
Walkthrough: Using Automation to Write a Letter in Microsoft Office Word
Walkthrough: Using Automation to Create a Graph in Microsoft Excel

Concepts

COM Overview
Programming Best Practices
Security and Protection