Click or drag to resize

Accessing a UI extension from VBScript

User interface extensions can include functionality that you can access from VBScript with the AMCreateObject function. The function creates and returns a reference to an object that is provided by an automation server. Automation objects are special objects visible to COM that applications (called automation servers) make available to other applications (called automation clients). The objects make it possible for functionality or data within one application to be used inside the other application.

To create an automation object accessible from VBScript:

  1. In a Visual Basic .NET user interface extension project, select Add New Item from the Project menu. The Add New Item dialog appears.
  2. Select the BC Meridian Script Object template from the BC-Meridian category and click Add. The class definition of an automation object is added to the project.
  3. Open the class in the code editor and change the value of the ProgId attribute to the desired value.
  4. Define the public methods and properties that you would like accessible from VBScript. Use the Repository property of the class to get the current transaction object. You can also use the Services property of the class to get the client application context object. The context is initialized only when the object is created on a client by passing False to the AMCreateObject function for the second parameter (OnServer=False). For a server-side initialization (OnServer=True), the property returns a null value.

When an automation client calls a .NET object, the common language runtime creates the managed object and a COM callable wrapper (CCW) for the object. Automation clients cannot reference a .NET object directly and use the CCW as a proxy for the managed object.

Unlike the .NET client that it wraps, the CCW tracks references in traditional COM fashion. When the reference count on the CCW reaches zero, the wrapper releases its reference on the managed object. A managed object with no remaining references is collected during the next garbage collection cycle. This means that a CCW does not provide deterministic release of the wrapped .NET object. You should explicitly release the automation object with the Dispose method.

Following is VB.NET code that defines an automation object that is accessible from VBScript with the ProgIdMyExtension.MyCommand:

Automation object definition
<ComVisible(True)> _
<Guid("157c3132-a03a-4c85-8b8c-6fcf0d339f52")> _
<ClassInterface(ClassInterfaceType.AutoDispatch)> _
<ProgId("MyExtension.MyCommand")> _
Public Class MyCommand
  Inherits BCScriptCallableObject

  Public Sub DoIt(ByVal userName As String)
    MessageBox.Show( _
     "Hello: " + userName + Environment.NewLine + _
     "Server time is: " + Repository.ServerTime)
  End Sub

End Class

Follwing are descriptions of the attributes applied to the class:

Following is Meridian Enteprise VBScript code that demonstrates the usage of the defined automation object:

VBScript creating an automation object with explicit disposal
Sub ExecuteMyCommand()
  'Create script callable object.
  Set myObject = AMCreateObject("MyExtension.MyCommand")  
  Call myObject.DoIt(User.Name)
  'Release script callable object.
    Call myObject.Dispose
  Set myObject = Nothing  
End Sub

There is a problem with releasing an automated object explicitly this way. It does not guarantee that Dispose is called even if an error occurs (in VB.NET the Using statement is intended for that).

To solve this problem we recommend the following solution. In VBScript, define a helper class that represents a wrapper of the automated object. The approach is demonstrated with the following code sample:

VBScript creating a wrapper object with deterministic release
Sub ExecuteMyCommand()
  'Create script callable object.
  Set myObject = New MyScriptObject  
  Call myObject.MyCommand.DoIt(User.Name)
  'Release script callable object.
  Set myObject = Nothing  
End Sub

'Represents a wrapper of a COM object accessible from VBScript.
'Provides deterministic release of resources.
Class MyScriptObject
  Private underlyingObject

    'Initializes the COM object.
  Private Sub Class_Initialize()
      Set underlyingObject = AMCreateObject("MyExtension.MyCommand")
    End Sub

    'Releases the COM object.
  Private Sub Class_Terminate()
      underlyingObject.Dispose()
        Set underlyingObject = Nothing
  End Sub

   'Gets the COM object.
  Public Property Get MyCommand
    Set MyCommand = underlyingObject
  End Property

End Class
See Also