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.

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