Calling Functions From .NET Assemblies

Requirements

Calling .NET routines via dotNET Object

Calling .NET Routines via Application Domain

Calling .NET Routines With Optional Parameters

Working With Values Returned by .NET Routines

Samples

• A license for the TestComplete Desktop module.

• The .NET Classes Support feature enabled in TestComplete.

  If you experience issues with accessing .NET classes, select File | Install Extensions from the TestComplete main menu and check whether the .NET Classes Support feature is enabled.

You can use a special dotNET object to access .NET assemblies, types and type members.

Configuring Project’s CLR Bridge Settings

Calling Routines From .NET Assemblies

Assemblies added to the CLR Bridge options become available in scripts as child objects of the dotNET object. Types defined in a specific assembly are, in their turn, child objects of the assembly node. The object corresponding to a type provides access to subtypes, static members and constructors defined in this type.

The Code Completion window shows all the available assemblies, types and type members:

To call static members of a .NET class:

dotNET.namespace.class.subclass.method(parameters)

dotNET.namespace.class.subclass.property(parameters)

TestComplete automatically converts simple data types (such as strings, integers and Booleans) you pass as parameters to .NET-compatible values. You can pass parameters of the Object type to the CLR Bridge engine only if they are descendants of the System.Object class. Otherwise, a type mismatch error will occur.

Separate the namespace and class name (and subclass name) using dots. Replace the dots used in the namespace name with an underscore character.

To call non-static members:

First create an instance of the needed class by calling the class constructor or a static member that create a new class instance:

dotNET.namespace.class.zctor()

dotNET.namespace.class.zctor_2(parameters)

Note:

Normally, the class constructor name is _ctor(). A class can have several constructors ( _ctor(), _ctor2(), _ctor3(), etc). However, in VBScript an identifier cannot begin with an underscore ( _ ). Therefore, to keep _ctor methods compatible with VBScript, TestComplete replaces the leading underscore character with the letter z in method names. For example, to call the _ctor3 method, use zctor_3.

For more information on creating instances of .NET classes in scripts, see Creating Instances of .NET Classes Defined in Applications.

All process objects that correspond to .NET applications have the AppDomain method. The method provides access to the application domain. The object returned by the AppDomain method is a wrapper for the .NET AppDomain object.

TestComplete adds an extra dotNET property to the underlying .NET AppDomain object. The property provides access to classes defined in the application and to classes defined in assemblies loaded to the application domain.

To call a class member via AppDomain:

To call a non-static member:

For more information on creating instances of .NET classes in scripts, see Creating Instances of .NET Classes Defined in Applications.

The advantage of the AppDomain.dotNET property over the dotNET object is that you can create instances of application classes without adding application assemblies to the project’s CLR Bridge list.

If you need to create a .NET object to pass it as a parameter to an application routine, we recommend that you create that object by using the application domain. This way you will be able to avoid compatibility issues if you have several versions of .NET Framework installed on your computer.

You cannot pass non-.NET objects as parameters to .NET application routines. For more information, see Creating Instances of .NET Classes Defined in Applications.

TestComplete does not allow omitting optional parameters when calling .NET functions from your tests. That is, you must specify all the parameters in the call, including the optional ones.

This means that if you want to use the default parameter values, you have to specify them explicitly in the call. A partial workaround to this is passing dotNET.System.Type.Missing as optional parameter values. For example, if you have a method declared in the following way —

— then to call it from TestComplete scripts, you can use the following code:

Note, however, that this workaround does not work for integer, double and boolean optional parameters. You can use it for string, date, object and other parameter types. As for the integer, boolean or decimal optional parameters, you have to specify appropriate integer, double and boolean values in the call.

In .NET, all data types are objects. Therefore, there are some specifics of using values returned from .NET routines in your tests:

• .NET integer, double and boolean values are compatible with TestComplete data types. You can use them in tests directly.

• Access the values of .NET Decimal and DateTime objects and of enumerable members via the OleValue property.

  For example, to access the System.DataTime.UtcNow property holding the current UTC time:

  JavaScript, JScript

  Python

  VBScript

  DelphiScript

  C++Script, C#Script

  JavaScript, JScript

  dotNET.System.DateTime.UtcNow.OleValue

  Python

  dotNET.System.DateTime.UtcNow.OleValue

  VBScript

  dotNET.System.DateTime.UtcNow.OleValue

  DelphiScript

  dotNET.System.DateTime.UtcNow.OleValue

  C++Script, C#Script

  dotNET["System"]["DateTime"]["UtcNow"]["OleValue"]

  In some cases, you can use OleValue with .NET strings (System.String objects). For example, you may need to use OleValue to pass a string value as a parameter to a user-defined script function or to compare the value with another string.

• Single-dimensional .NET arrays have the extra OleValue property that returns a Variant-compatible array. This way you can use native array operations and functions of scripting languages with the returned array.

  For example, in VBScript, you can use the LBound and UBound functions to determine an array’s lower and upper bounds and access array elements using the parenthesis syntax: arr(index).

  In JScript, С#Script and C++Script arrays obtained via the OleValue property are not compatible with native array formats. They should be first converted to native arrays by using the toArray() method.

  JavaScript

  JScript

  Python

  VBScript

  DelphiScript

  C++Script, C#Script

  JavaScript

  function newTest()
  {
    var dotnet_str = dotNET.System.String.Copy("Hello, world!");
    var dotnet_array = dotnet_str.ToCharArray();
    
    // Converting to a native array
    var array2 = dotnet_array.OleValue;
    for(let i = 0; i < array2.length; i++)
    Log.Message(array2[i]);
  }

  JScript

  function newTest()
  {
    var dotnet_str = dotNET.System.String.Copy("Hello, world!");
    var dotnet_array = dotnet_str.ToCharArray();
    
    // Converting to a native array
    var array2 = dotnet_array.OleValue.toArray();
    
    for(var i = 0; i < array2.length; i++)
    Log.Message(array2[i]);
    
  }

  Python

  def newTest():
    dotnet_str = dotNET.System.String.Copy("Hello, world!")
    dotnet_array = dotnet_str.ToCharArray()
   
    # Converting to a native array
    array2 = dotnet_array.OleValue
    
    for i in range(len(array2)):
      Log.Message(array2[i])

  VBScript

  Sub newTest
    Dim dotnet_str, dotnet_array, array2, i
    
    Set dotnet_str = dotNET.System.String.Copy("Hello, world!")
    Set dotnet_array = dotnet_str.ToCharArray()
    
    ' Converting to a native array
    array2 = dotnet_array.OleValue
    
    i = 0
    For i = LBound(array2) To UBound(array2)
      Log.Message(array2(i))
    Next
  End Sub

  DelphiScript

  procedure newTest;
  var dotnet_str, dotnet_array, array2, i;
  begin
    dotnet_str := dotNET.System.String.Copy('Hello, world!');
    dotnet_array := dotnet_str.ToCharArray();
    
    // Converting to a native array
    array2 := dotnet_array.OleValue;
    
    for i := VarArrayLowBound(array2,1) to VarArrayHighBound(array2,1) do
      Log.Message(array2[i]);
  end;

  C++Script, C#Script

  function newTest()
  {
    dotnet_str = dotNET["System"]["String"]["Copy"]("Hello, world!");
    dotnet_array = dotnet_str["ToCharArray"]();
     
    // Converting to a native array
    array2 = dotnet_array["OleValue"]["toArray"]();
    
    for(var i = 0; i < array2.length; i++)
    Log["Message"](array2[i]);
  }

  Alternatively, you can use the GetValue method to access .NET array items.

  JavaScript

  JScript

  Python

  VBScript

  DelphiScript

  C++Script, C#Script

  JavaScript

  function arrayTest()
  {
    var dotnet_str = dotNET.System.String.Copy("Hello, world!");
    var dotnet_array = dotnet_str.ToCharArray();
    
  
    for(let i = 0; i < dotnet_array.Length; i++)
    {
      var elem = dotnet_array.GetValue(i);
      Log.Message(elem);
    }
  }

  JScript

  function arrayTest()
  {
    var dotnet_str = dotNET.System.String.Copy("Hello, world!");
    var dotnet_array = dotnet_str.ToCharArray();
    
  
    for(var i = 0; i < dotnet_array.Length; i++)
    {
      var elem = dotnet_array.GetValue(i);
      Log.Message(elem);
    }
  }

  Python

  def arrayTest():
    dotnet_str = dotNET.System.String.Copy("Hello, world!")
    dotnet_array = dotnet_str.ToCharArray()
   
    for i in range(dotnet_array.Length):
     Log.Message(dotnet_array.GetValue(i))

  VBScript

  Sub arrayTest
    Dim dotnet_str, dotnet_array, array2, i, elem
    
    Set dotnet_str = dotNET.System.String.Copy("Hello, world!")
    Set dotnet_array = dotnet_str.ToCharArray()
    
    For i = dotnet_array.GetLowerBound(0) To dotnet_array.GetUpperBound(0)
      Log.Message(dotnet_array.GetValue(i))
    Next
  End Sub

  DelphiScript

  procedure arrayTest;
  var dotnet_str, dotnet_array, array2, i, elem;
  begin
    
    dotnet_str := dotNET.System.String.Copy('Hello, world!');
    dotnet_array := dotnet_str.ToCharArray();
    
    for i := dotnet_array.GetLowerBound(0) to dotnet_array.GetUpperBound(0) do
     Log.Message(dotnet_array.GetValue(i));
  end;

  C++Script, C#Script

  function arrayTest()
  {
    dotnet_str = dotNET["System"]["String"]["Copy"]("Hello, world!");
    dotnet_array = dotnet_str["ToCharArray"]();
     
    for(var i = 0; i < dotnet_array.Length; i++)
    {
      var elem = dotnet_array["GetValue"](i);
      Log["Message"](elem);
    }
  }

• Two- and multidimensional .NET arrays do not have the OleValue property. To get the array elements, use its native Get(index1, index2, ..., indexN) method.

• To work with other objects, use their internal properties and methods.

The following example shows how you can create a System.String object (defined in the mscorlib assembly) and call methods of this object in scripts:

def Test():

  # Calling a class instance constructor
  str = dotNET.System.String.zctor_8(0x41, 3)
  Log.Message(str.OleValue) # Using the OleValue property

  # Calling a static method
  str = dotNET.System.String.Copy("Hello, world!")

  # Calling a class instance (non-static) method
  i = str.IndexOf("w")
  Log.Message(i)

TestComplete also includes a sample project that shows how to call functions from .NET assemblies via the dotNET object: