• Article

AutomationFactory Class

Microsoft Silverlight will reach end of support after October 2021. Learn more.

Provides access to registered Automation servers.

Inheritance Hierarchy

System.Object
  System.Runtime.InteropServices.Automation.AutomationFactory

Namespace:  System.Runtime.InteropServices.Automation
Assembly:  System.Windows (in System.Windows.dll)

Syntax

'Declaration
Public NotInheritable Class AutomationFactory

public static class AutomationFactory

The AutomationFactory type exposes the following members.

Properties

  Name Description
Public propertyStatic member IsAvailable Gets a value that indicates whether the Automation feature in Silverlight is available to the application.

Top

Methods

  Name Description
Public methodStatic member CreateObject(String) Activates and returns a reference to the registered Automation server with the specified programmatic identifier (ProgID).
Public methodStatic member CreateObject<T>() Not yet implemented.
Public methodStatic member GetEvent Gets an object that represents the specified event of the specified Automation server.
Public methodStatic member GetObject Gets a reference to the previously activated and currently running Automation server with the specified programmatic identifier (ProgID).

Top

Remarks

Automation is a Windows-based technology that applications use to expose functionality to scripting tools and other applications. For example, you can use Automation to add Office features to your Silverlight-based applications.

An application or component exposing functionality is called an Automation server; an application accessing the functionality is called an Automation client. Because Automation servers must be preinstalled and run in full trust, Silverlight enables only trusted applications to serve as Automation clients. For more information, see Trusted Applications.

This reference topic describes Silverlight Automation support. For usage examples, see How to: Use Automation in Trusted Applications. For more information about Automation in general, see Automation.

Accessing Automation Servers

To access an Automation server, you should first check the IsAvailable property. This property returns true only for trusted applications running outside the browser on Windows.

If Automation is available, you can use the CreateObject or GetObject method to retrieve a late-bound reference to an Automation server. To use the reference as a late-bound object, you must assign it to a variable of type Object in Visual Basic or type dynamic in C#.

NoteNote:

The use of type dynamic requires a reference to Microsoft.CSharp.dll.

Identifying Automation Servers

You identify Automation servers using programmatic identifiers or progIDs. When a user installs an application that provides Automation support, the application registers progID values so that external applications can locate them.

Silverlight can use only Automation servers that are already installed; therefore, the CreateObject and GetObject methods throw exceptions when they cannot find the requested progID.

The following list shows a few common progID values:

  • Office Automation: Outlook.Application, Excel.Application, PowerPoint.Application

  • System Automation: Scripting.FileSystemObject, WScript.Shell, Shell.Application

  • Windows Management Instrumentation: WbemScripting.SWbemLocator

In general, these strings map to particular versions of Automation servers. If multiple versions of a server are available, the server typically adds a version number to the progID.

To find documentation and information about these and other Automation servers, perform Web searches using phrases such as "PowerPoint object model" and "CreateObject PowerPoint.Application". Note that most Automation documentation samples are in VBScript, which you need to adapt to your preferred Silverlight language.

Automation Support

Silverlight supports only late bound, IDispatch-based access to Automation servers that are already installed and registered on the user's computer. Silverlight does not support the deployment of Automation-based dependencies.

Late binding requires the manipulation of Automation objects as type Object in Visual Basic and type dynamic in C#. This means that Visual Studio provides no IntelliSense support or compiler warnings to help prevent errors. As a result, you should check the object model documentation for the Automation server you are using, and test your code thoroughly.

Silverlight provides the following Automation support:

  • CreateObject and GetObject support for accessing new or running in-proc or out-of-proc Automation servers by progID.

  • Late-bound access to Automation properties (including indexed properties) and methods (including by ref and by value arguments). Silverlight supports positional and optional method parameters, but does not support named parameters.

  • Support for Automation events, excluding events with return values. Support includes the option to use standard Visual Basic or C# event syntax, custom delegates, or the AutomationEvent helper class. However, Visual Basic does not support the use of custom delegates to handle events with optional parameters.

  • Built-in variant conversion for specific VARIANT types, BSTR, and SAFEARRAY, but excluding support for user-defined types and multi-dimensional or jagged arrays.

  • Support for inbound conversion of IEnumVARIANT-based collections to IEnumerator instances to enable for-each processing.

Type Conversion

The following tables indicate which Silverlight types correspond to which native VARIANT types.

Silverlight type

Native VARIANT type

Byte

VT_UI1

UInt16

VT_UI2

UInt32

VT_UI4

UInt64

VT_UI8 (Not available on Windows 2000.)

SByte

VT_I1

Int16

VT_I2

Int32

VT_I4

Int64

VT_I8 (Not available on Windows 2000.)

Char

VT_UI2 (Managed-to-native conversion only, although native-to-managed conversion occurs for Char method arguments passed by reference. Note, however, that this conversion is not supported for Char arrays.)

Single

VT_R4

Double

VT_R8

Boolean

VT_BOOL

String

VT_BSTR

Decimal

VT_DECIMAL (Conversion in both directions.)VT_CY (Native-to-managed conversion only.)

DateTime

VT_DATE

IEnumerator

IEnumVARIANT (Native-to-managed conversion only; managed-to-native conversion is not supported.)

automation object

VT_DISPATCH

COM object

VT_UNKNOWN

unhandled native variant

As itself

arrays of any previous type, excluding unhandled native variants

VT_ARRAY | type

arrays of Object or type dynamic where each element is something in this table

VT_ARRAY | VT_VARIANT (Conversion in both directions.) VT_ARRAY | VT_UNKNOWN (Native-to-managed conversion only.)

nulla null reference (Nothing in Visual Basic)

VT_EMPTY

DBNull.Value

NULL

Type.Missing

VT_ERROR, scode == DISP_E_PARAMNOTFOUND

null Automation object reference

VT_DISPATCH, pdispVal == NULL

null COM object reference

VT_UNKNOWN, punkVal == NULL
NoteNote:

In C#, when you call Automation methods with array parameters, the arrays are passed by value unless you specify the ref keyword.

Examples

The following code example demonstrates how to use this class.

This example is part of a larger example in How to: Use Automation in Trusted Applications.

Private outlook As Object

Private Function InitializeOutlook() As Boolean

    Try
        ' If GetObject throws an exception, then Outlook is 
        ' either not running or is not available.
        outlook = AutomationFactory.GetObject("Outlook.Application")
        Return True
    Catch
        Try
            ' Start Outlook and display the Inbox, but minimize 
            ' it to avoid hiding the Silverlight application.
            outlook =
                AutomationFactory.CreateObject("Outlook.Application")
            outlook.Session.GetDefaultFolder(6).Display() ' 6 = Inbox
            outlook.ActiveWindow.WindowState = 1  ' minimized
            Return True
        Catch
            ' Outlook is unavailable.
            Return False
        End Try
    End Try

End Function

private dynamic outlook;

private bool InitializeOutlook()
{
    try
    {
        // If GetObject throws an exception, then Outlook is 
        // either not running or is not available.
        outlook = AutomationFactory.GetObject("Outlook.Application"); 
        return true;
    }
    catch (Exception)
    {
        try
        {
            // Start Outlook and display the Inbox, but minimize 
            // it to avoid hiding the Silverlight application.
            outlook = 
                AutomationFactory.CreateObject("Outlook.Application");
            outlook.Session.GetDefaultFolder(6 /* Inbox */).Display();
            outlook.ActiveWindow.WindowState = 1; // minimized
            return true;
        }
        catch (Exception)
        {
            // Outlook is unavailable.
            return false;
        }
    }
}

Version Information

Silverlight

Supported in: 5, 4

Platforms

For a list of the operating systems and browsers that are supported by Silverlight, see Supported Operating Systems and Browsers.

Thread Safety

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.