Best Practices for Using Automation With the RoleTailored Client

With Automation, Windows-based applications, such as Microsoft Office products, expose Automation objects that Microsoft Dynamics NAV 2009 can access and run using an Automation controller in C/SIDE. In the Classic client, Automation objects are always run on the Classic client. In the RoleTailored client, you can choose to run Automation objects either on the RoleTailored client or Microsoft Dynamics NAV Server. By default, the Automation object runs on the RoleTailored client.

Because Automation objects expose a COM interface, Automation can affect both performance and security, depending on whether you run Automation objects on the RoleTailored client or Microsoft Dynamics NAV Server. 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 whether Automation objects run on the RoleTailored client or Microsoft Dynamics NAV Server by using the CREATE Function (Automation) in C/AL code of the object that runs the Automation object.

Automation Object Implementation Overview

Use the following figure and table to help you decide whether to run the Automation object on the RoleTailored client or Microsoft Dynamics NAV Server based on the Automation object's characteristics.

Ee909565.Local_1149799321_navrtcautomationobjectoverview(en-us,NAV.60).png

Automation object RoleTailored client Microsoft Dynamics NAV Server Remarks

Native code Automation objects that use out-of-process Automation servers

X

This includes Microsoft Office Automation Objects. For more information, see Native and Managed Automation Objects.

Automation objects with a user interface, such as OCX types

X

OCX controls cannot run on Microsoft Dynamics NAV Server.

Automation objects that execute as single-threaded apartments

X

For more information, see Single-Threaded Apartment and Multithreaded Apartment Automation Objects.

Managed code Automation objects

X

X

Managed code Automation objects can run on either the RoleTailored client or Microsoft Dynamics NAV Server. For more information, see Native and Managed Automation Objects.

Native code Automation objects that use in-process Automation servers

X

X

This includes DLLs, such as MSXML.dll. For more information, see Native and Managed Automation Objects.

Automation objects that execute as multithreaded apartments

X

For more information, see Single-Threaded Apartment and Multithreaded Apartment Automation Objects.

Automation objects that stream parameters and are configured to receive events

X

You need to install COM objects on the computer running Microsoft Dynamics NAV Server. You also need to install COM objects on the computers running the clients that will use them.

If you choose to run an Automation object on Microsoft Dynamics NAV Server, then see Considerations When Running Automation Objects on Microsoft Dynamic NAV Server.

Single-Threaded Apartment and Multithreaded Apartment Automation Objects

Automation objects can be designed to execute as multithreaded apartments (MTA) or single-threaded apartments (STA).

  • MTA Automation objects are designed for highly reentrant, stressed environments with high throughput for multiple clients. They are most suitable for server-side components.

  • STA Automation objects are designed to provide resource-intensive functionality in a single client environment. For example, the Automation objects of Microsoft Office products are STA-based.

As a best practice, you should:

  • Run STA Automation objects, including Microsoft Office products, on the RoleTailored client.

  • Run MTA Automation objects on Microsoft Dynamics NAV Server.

You can run an STA Automation object on Microsoft Dynamics NAV Server and an MTA Automation object on the RoleTailored client because the .NET Framework manages marshaling between MTA and STA. However, in doing so, you may decrease performance. Some Automation objects are available in both MTA and STA versions, so you can choose. 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 PRB: MSXML Performance Bottleneck in ShareMutex Under Stress Microsoft Support Knowledge Base article.

Native and Managed Automation Objects

The RoleTailored client and Microsoft Dynamics NAV Server both support Automation objects that are created from either native or managed code. Automation in Microsoft Dynamics NAV 2009 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.

Considerations When Running Automation Objects on Microsoft Dynamic NAV Server

The following table includes recommendations to consider when you choose to run an Automation object on Microsoft Dynamics NAV Server.

If... Then…

The Automation object accesses a file

You may need to assign additional permissions to the account under which Microsoft Dynamics NAV Server is running. For more information, see Security.

The Automation object accesses a different computer than the computer running Microsoft Dynamics NAV Server

You may need to assign additional permissions or add exceptions to any firewalls. This allows the account under which Microsoft Dynamics NAV Server runs to work correctly.

The Automation object creates a file

You must use the FILE.DOWNLOAD functions to send the file from your user.

The Automation object consumes a file

You must use the FILE.UPLOAD functions to send the file from your user.

The application runs on both the Classic client and the RoleTailored client

You should use the ISSERVICETIER system function to differentiate code that runs on the Classic client and code that runs on the RoleTailored client. The following example shows how to use the ISSERVICETIER function for creating an Automation object. This example requires that you create the following variables.

Variable Data type
ResultBoolean
AutomationObjectAutomation
IF ISSERVICETIER THEN
    Result := CREATE(AutomationObject, TRUE, TRUE)
ELSE
    Result := CREATE(AutomationObject, TRUE);

Security

Changing the Microsoft Dynamics NAV Server Account

By default, the Microsoft Dynamics NAV Server service runs using the Network Service account. The Network Service account does not have permissions to initiate new processes that are configured in Component Services for Windows. This is done to prevent out-of-process Automation servers from running on Microsoft Dynamics NAV Server. We do not recommend that you change this behavior.

If your scenario requires that you change this behavior, then you should create a new account for the Microsoft Dynamics NAV Server service that has launch and activate permissions on the required Automation servers. Automation processes will be created on the server and remain active until they receive a command to terminate or until Microsoft Dynamics NAV Server is restarted.

Preventing Users from Sharing Automation Processes

One risk with running Automation servers on Microsoft Dynamics NAV Server, which is not a risk when running Automation objects on the RoleTailored client, is that users could potentially share the same Automation process. For example, consider the CREATE Function (Automation) in C/AL code of your Automation controller. If you use the construct CREATE (automationServer, TRUE), then the system will search for all created instances of type automationServer and try to reuse them. This can potentially result in the current process reading data that was created by another user. To prevent this, use the construct syntax CREATE (automationServer, FALSE, FALSE) for Automation servers running on Microsoft Dynamics NAV Server.

This is not an issue when running Automation objects on the RoleTailored client because sharing cannot occur, so reusing Automation server instances is acceptable.

In-Process Automation Objects and OCX Controls

In-process Automation objects and OCX controls always run under the same user account as the RoleTailored client when run on the RoleTailored client or Microsoft Dynamics NAV Server. This is because in-process Automation objects are hosted by the current running process and inherit the security properties of the active user. The behavior is different for out-of-process Automation objects that run on Microsoft Dynamics NAV Server. These objects run under the security context of the service account, such as Network Services.

See Also

Tasks

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

Concepts

COM and C/SIDE Overview
How to: Create an Automation Controller in C/SIDE
Programming Best Practices
Security in the RoleTailored Environment