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.
.png "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