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
	IsAvailable	Gets a value that indicates whether the Automation feature in Silverlight is available to the application.

Top

Methods

	Name	Description
	CreateObject(String)	Activates and returns a reference to the registered Automation server with the specified programmatic identifier (ProgID).
	CreateObject<T>()	Not yet implemented.
	GetEvent	Gets an object that represents the specified event of the specified Automation server.
	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#.

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

Note:
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.

See Also

Reference

System.Runtime.InteropServices.Automation Namespace

Other Resources

Trusted Applications

How to: Use Automation in Trusted Applications

Automation