Automation Objects in Microsoft Dynamics NAV 2009

Automation Objects in Microsoft Dynamics NAV 2009

  • Comments 7

Overview

The Automation object is often used to integrate NAV business logic with external processes and thereby extend the functionality of the product, such as integration with other products like Office. Automation objects must expose a COM interface, and every time we cross a process boundary is worth thinking about performance, but issues that involve correct operation could have a negative impact on performance. This is something we are willing to accept. One example is that objects designed for a single thread execution must execute on Single Threaded Apartment (STA) threads. Having a look at this KB article (http://support.microsoft.com/kb/257757/) explains why office products never should be allowed to run on the server:

Reentrancy and scalability: Server-side components need to be highly reentrant, multi-threaded COM components that have minimum overhead and high throughput for multiple clients. Office applications are in almost all respects the exact opposite. Office applications are non-reentrant, STA-based Automation servers that are designed to provide diverse but resource-intensive functionality for a single client. The applications offer little scalability as a server-side solution. Additionally, the applications have fixed limits to important elements, such as memory. These cannot be changed through configuration. More importantly, the applications use global resources such as memory mapped files, global add-ins or templates, and shared Automation servers. This can limit the number of instances that can run concurrently and can lead to race conditions if the applications are configured in a multi-client environment. Developers who plan to run more than one instance of any Office application at the same time need to consider "pooling" or serializing access to the Office application to avoid potential deadlocks or data corruption.”

Architecture

clip_image001

Flavors of COM

Apartment threading

There are two major flavors of Automation objects, ones that are designed for single threaded applications, and ones that execute well in a multithreaded environment. This doesn’t prevent one from running STA objects on the server and MTA objects on the client, but each scenario where “best practices” are deviated should be considered closely.

An example would be the XML Document object

clip_image003

The DOMDocument is a single threaded apartment version and the FreeThreadedDOMDocument is the version that utilizes a multithreaded environment, like the server. But in cases where we a free threaded version of the object is not available, it would properly be acceptable to use the version available, because the .Net runtime is managing MTA-to-STA marshaling behind the scene. This could result in bad performance and other problems – but in most scenarios it is likely to work. A closer look at “PRB: MSXML Performance Bottleneck in ShareMutex Under Stress” explains why issues like these must be considered.

“Using the MSXML parser in a high-stress environment … may cause unusually long run times on XML requests, and the application or service can appear to stop responding (hang).“

And the solution in this scenario would be to use the FreeThreadedDOMDocument object on the server.

Native and Managed Automation Objects

The Automation implementation in the Role Tailored Client and the Dynamics NAV Server utilizes the CLR implementation, and the CLR does an excellent job of allowing managed code to call out to unmanaged Automation objects. It generates a runtime-callable wrapper (RCW) proxy that implements all of the interfaces of the underlying object. Furthermore, the CLR has a built-in mapping/marshaling layer that knows how to translate the types between the native and managed domains.

The following table shows the specific type mappings between AL, COM and their corresponding .NET types.

clip_image004

All the Automation objects are late bound activated; this means that they must implement the IDispatch interface, in order for the Reflection API to be able to invoke members. Managed Automation objects are recognized by the RCW as being managed and standard CLR reflection invocation takes place. Therefore, in-process (dll) and Out-of-process (exe) Automation behaves identically if the objects are created in a managed language.

Security

The default account for running the NAV Server, configured at installation time, is the built-in Network Service account. This account does not have permissions to spawn a new process, as configured in Component Services, and it is not recommended to change that behavior. This is by design, in order to prevent out-of-process Automation servers (Executables with a COM Interface) to execute on the server. But if the scenario requires this, it would be a recommended practice to create a new service account with the minimum privileges plus the “Launch and Activate Permissions” of the required Automation Servers. These processes will then be created on the server and properly stays alive until they receive a specific terminate command, or the server is rebooted. Another risk with Automation servers on the NAV Server machine is that users could potentially share the same Automation process. In AL, the construct CREATE (automationServer, TRUE), will search the system for created instances of type “automationServer” and try to reuse that process, and potentially read data created by another user.

Therefore the recommended syntax would be CREATE(automationServer, FALSE, FALSE), for Automation servers running on the NAV Server. On the client tier, no sharing can occur and it would be perfectly fine to try and reuse the Automation server.

The in-process Automation objects whether they are created on the client or server tier are hosted by the running process and inherit the security context of the active user. The same goes for OCX controls that require an UI and therefore only will be allowed on the client side.

Wrap-up (recommendations)

Server tier
    • Native Automation objects: In-process automation servers, like MSXML6.dll.
    • Objects with a user interface such as OCX types.
    • Managed wrapped COM Objects
    • Objects designed for multi threaded execution (MTA)
Client tier
  • Native Automation objects: Out of process automation servers, like Microsoft Office.
  • Objects with a user interface such as OCX types.
  • Objects designed for single threaded execution (STA)
General
  • It is good practice to design your Automation interfaces to get as much work done in a single method invocation. And when consuming a component, try to use it in way that minimizes chattiness. This is utmost importance for the client side automation scenario.

Sample

COM is an immutable, interface-based model. Interface design is very important and should always be split from the implementation. Try to avoid auto-generated interfaces based on classes as they have a tendency to violate this guideline and not version well. There is a good source of information at: “Do not use AutoDual ClassInterfaceType“

image

(see the first comment on this post for the text of this sample)

- Stefan Omdahl

Leave a Comment
  • Please add 5 and 5 and type the answer here:
  • Post
  • The sample code above was inserted as an image to ensure formatting (and thus readability) was retained on all platforms.

    If you're interested in cutting and pasting this code, the text follows

    -------------------------------------

    namespace AutomationSample

    {

    // Apply InterfaceType (ComInterfaceType.InterfaceIsIDispatch) to an interface to produce metadata to restrict callers to late binding only

       [InterfaceType(ComInterfaceType.InterfaceIsIDispatch)]

       [Guid("662D91A9-91DC-4cd7-8A7A-F75D6415EBAA")]

       public interface INavAutomationSample

       {

           string Property1{get;set;}

           void Method1();

    // COM is case insensitive and therefore having two methods with the same name must be avoided.        

           void method1();

           String Method2(String s);

       }

    // Indicates that no class interface is generated for the class. If no interfaces are implemented explicitly, the class can only provide late bound access through the IDispatch interface. This is the recommended setting for ClassInterfaceAttribute. Using ClassInterfaceType.None is the only way to expose functionality through interfaces implemented explicitly by the class.

       [ClassInterface(ClassInterfaceType.None)]

    // The guid used to identify the COM object

       [Guid("F1832C1E-DEDA-4333-B074-95F85F8BFDA1")]

       public class NavAutomationSample : INavAutomationSample

       {

           public string Property1

           {

               get { return s; }

               set { s = value; }

           }

           public void Method1(){}

           public void method1(){}

           public String Method2(String s)

           {

               return s;

           }

       }

    }

  • For more information on Automation objects in Nav, along with a full sample solution (with FOB/TXT files) for a 'Hello World' automation object via a .Net class, see my recent posting at http://adventuresindotnet.blogspot.com/2008/12/nav-automation-object.html.  

       Tim Larson

  • Are these considerations also important for the classic client when used in Citrix or Terminal Server enviroment?

  • The classic client is handling automation objects in a different way. So unless you're planning for an upgrade, there is no reasons to consider the automation topics discussed in this blog.

  • Thanks - I feared I had to change all the places I use  XMLDOM :-)

  • Tag this post with .NET so it can be found later more easily?

  • Tagged with .NET.

    Thanks!

Page 1 of 1 (7 items)