The SocketTools Scripting Edition components can be used with Visual C# much in the same way that the components are used in Visual Basic 6.0. Interoperability between the COM components and the .NET Framework is managed by an intermediate library called a runtime callable wrapper (RCW) which makes the COM component appear as a native .NET component.

Creating Objects

To use one of the scripting components in your application, you first need to add a reference to the object in your project. To include it in your project, right click on References in the Solution Explorer and select Add Reference. This will display a dialog box which lists the available components. Select the COM tab and scroll down to the component that you wish to add and click the Select button. The selected component will be displayed and you can click OK to add it to the project. If you don't see the component there, try clicking on the Browse button and then entering the name of the DLL. Note that if you have other SocketTools Editions installed, you may see references to those libraries and/or controls. Make sure that you're selecting the component that has the word "Object" in the name.

Once the component has been added to your project, you should import the object types into the current namespace. This is done with a using statement near the beginning of the program with the other using statements. For example, if you were using the File Transfer Protocol component, you would add:

using System.Reflection;
using System.Runtime.InteropServices;
using FtpObjectLib;

To determine the namespace and class name for the component that you're using, refer to the Technical Reference. You can also select View | Object Browser from the menu to display the available objects and browse their properties and methods. Next, you create an instance of the object class in your project using the new keyword. For example:

FtpObject ftpClient = new FtpObjectClass();

From that point forward, you can access the properties and methods of the component as you would any other class. One thing to keep in mind is that when the object is destroyed or goes out of scope, it will not be immediately released. This is the result of how garbage collection works in .NET, which means that the resources allocated by the component will not be immediately returned to the system. To force the component to release any resources it has allocated, you can use the System.Runtime.InteropServices.Marshal.ReleaseComObject function.

Initialization

After an instance of the object has been created, the next step that you need to take is to call the Initialize method. This will prepare the component for use, validating the runtime license, loading any required networking libraries and allocating the system resources that it requires. The Initialize method has several optional arguments, however in most cases the only argument that is required is the runtime license key. This is a string of characters which is used to validate your development license. It is important to note that the runtime key is not your product serial number. For more information, refer to the section on Component Initialization. The following code demonstrates how the FTP component can be initialized:

const string CSTOOLS6_LICENSE_KEY = ""; // // Set this to the runtime license key string

int nError = (int)ftpClient.Initialize(
    CSTOOLS6_LICENSE_KEY,
    Missing.Value,
    Missing.Value,
    Missing.Value);

if (nError != 0) 
{
    MessageBox.Show("Unable to initialize SocketTools component");
    return;
}

When the runtime callable wrapper is created, there are no optional arguments provided for the class. Optional arguments that are omitted should be specified using System.Reflection.Missing.Value as in the above example. Good coding practice also dictates that for every time the Initialize method is called, it should be matched with a call to the Uninitialize method before the object is destroyed or the script terminates. This tells the component to release any resources that were allocated. Note that if your script does not explicitly call the Uninitialize method, it will be done automatically when the object is destroyed.

Variants and Objects

The SocketTools component interface is essentially the same in C# as it is with other languages, however there are a few differences. In C#, variant data types are represented by the object type. This is important because all of the component methods and event arguments are typed as variants. This can lead to unexpected compiler errors when developing your application. Remember to cast the return value from the methods to the appropriate type, for example:

int nError = (int)ftpClient.Connect(
    strHostName, // Host name or IP address
    nHostPort,   // Port number
    strUserName, // User name, anonymous if omitted
    strPassword, // Password
    strAccount,  // Account name
    nTimeout,    // Timeout period
    nOptions);   // Options

Another common issue is that some of the methods in the SocketTools components expect arguments to be passed by reference, and the data is returned in the specified variable. An example of this is the GetDirectory method in the File Transfer Protocol component. The method expects a single argument, passed by reference. When the method returns, that argument will contain a string that specifies the current working directory. Because the method expects a variant type, you simply can't pass a string variable to the method. Instead, you need to use code like this:

object varDirectory = "";
int nError;

nError = (int)ftpClient.GetDirectory(ref varDirectory);
if (nError == 0)
{
    string strDirectory = varDirectory.ToString();
}

The varDirectory object is initialized to an empty string, and the ref keyword tells C# to pass the object by reference to the method. If the method returns a value of zero, which indicates success, then varDirectory contains the current working directory and that is assigned to a string variable.

Exception Handling

When setting a property, it is possible that the component will generate an exception as a result of an error. If these exceptions are not handled in your application, it will cause the program to halt and display a dialog box. To handle an exception, use the try..catch statement, such as:

try 
{
    ftpClient.HostAddress = "abcd";
}
catch (System.Runtime.InteropServices.COMException e)
{
    Console.WriteLine(e.Message.ToString());
    return;
}

In this example, the HostAddress property is being set to an illegal value (the HostAddress property only accepts IP addresses in dot notation, such as "192.168.0.1"). As a result, an exception is thrown and the catch section of code is executed. The ex argument contains information about the exception that has occurred, including an error number and a description of the error. In this case, that description is written to the console and the function is exited.

In addition to exceptions generated when properties are set to invalid values, it is also possible to have methods generate exceptions instead of returning error codes. To do this, set the ThrowError property to true. It allows you to write code like this:

try
{
    ftpClient.ThrowError = true;
    ftpClient.Connect(
        strHostName, // Host name or IP address
        nHostPort,   // Port number
        strUserName, // User name, anonymous if omitted
        strPassword, // Password
        strAccount,  // Account name
        nTimeout,    // Timeout period
        nOptions);   // Options

    ftpClient.ChangeDirectory(strDirName);
    ftpClient.ThrowError = false;
}
catch (System.Runtime.InteropServices.COMException e)
{
    ftpClient.ThrowError = false;
    Console.WriteLine("Error {0}: {1}", e.ErrorCode, e.Message.ToString());

    if (ftpClient.Connected)
    {
        ftpClient.Disconnect();
    }
    return;
}

In this example, the ThrowError property is set to true, and then the Connect and ChangeDirectory methods are called. If either of these methods fail, an exception will be thrown and the code in the catch section will be executed. In this case, the error code and description is written to the console, the client is disconnected and the function returns. By setting the ThrowError property and writing your code to use exception handling, it enables you to easily group function calls together and handle any potential errors, rather than individually checking the return value for each method.

Copyright © 2008 Catalyst Development Corporation. All rights reserved.