How To Write a Wrapper for a Command-Line Tool with Visual C# .NET (305994)

SUMMARY

This step-by-step article describes how to write a wrapper for a command-line utility that you want to use as an Automation object in Visual C# .NET and the Microsoft .NET framework with Visual Studio.

To successfully build a wrapper for a command-line utility for use as an Automation object, you need to be able to start the process, and then you need to obtain the output from the execution of the process. This procedure is divided into the following sections:

Write the code for the wrapper:
- Create a new class in which to house the wrapper code.
- Add an internal method to this class that will house the actual functionality of the program.
Use the wrapper in your application:
- Add your class file to a new application that will use this class.

back to the top

Build the Code for the Wrapper

To build the code for the wrapper, first create a new class in which to house the code. To do this, use Visual Studio or a text editor, such as Notepad, to create a new Visual C# .NET application.

Note: For the purposes of this article, the name of the sample Visual C# .NET application is LaunchEXE.

After you create the new class in which to house the code, add an internal method to this class that will house the actual functionality of the program. If you declare this method as internal, you can use it throughout your program; however, other applications outside of your program cannot access it.

To build the code:

Use the USING statement to declare to the compiler (refer to the first code fragment). The USING statement uses the resources of System.IO and System.Diagnostics in the following way:
- System.IO: To read and write to a StreamWriter object.
- System.Diagnostics: To start an external process from the application.
Declare the LaunchEXE class, and declare the public member function, Run, of the LaunchEXE class. The Run method returns a string to the caller. This string holds the output from LaunchEXE after the string completes its work. The following list describes the three arguments for the Run function:
- The first argument that is passed to the Run function is exeName; it is the name of the command-line tool application that you will start. This .exe file must reside in the same folder as the application that uses the class unless you specify a full path as another argument. In this article, assume that the .exe file is in the same folder as the application that you are building.
- The second argument that is passed to the Run function is argsLine. This argument consists of a string that contains arguments that you will pass on to the command-line tool.
- The third argument defines the time (in seconds) in which the .exe file must finish running, and return a result.
```
using System.Diagnostics;
using System.IO;
public class LaunchEXE
{
internal static string Run(string exeName, string argsLine, int timeoutSeconds)
}
					
```
Prepare the StreamReader object to handle the output that is received from the executed command-line tool. The StreamReader object performs the following functions:
- Reads the output that is created by the executable program.
- Creates a string that contains the output from the executable program. This output will be sent back to the calling application.
Set a Boolean value to FALSE, stating that this operation has not succeeded yet. You can set the Boolean value to TRUE after the operation completes successfully.
```
StreamReader outputStream = StreamReader.Null;
string output = "";
bool success = false;
					
```

Create a new process object, and then pass the executable program (LauncheEXE), and the arguments (argsLine) to run the command-line utility. In this sample, the CreateNoWindow property is used so that the MS-DOS window is suppressed each time you invoke your class to start the executable program.

try
{
	Process newProcess = new Process();
	newProcess.StartInfo.FileName = exeName;
	newProcess.StartInfo.Arguments = argsLine;
        newProcess.StartInfo.UseShellExecute = false;
        newProcess.StartInfo.CreateNoWindow = true;
	newProcess.StartInfo.RedirectStandardOutput = true;
	newProcess.Start();

If the operation does not time out, obtain the output from the suppressed MS-DOS window of the command-line utility, and then destroy the objects:

if (0 == timeoutSeconds)
	{
		outputStream = newProcess.StandardOutput;
		output = outputStream.ReadToEnd();
		newProcess.WaitForExit();
	}
	else
	{
		success = newProcess.WaitForExit(timeoutSeconds * 1000);
	
if (success)
	{
outputStream = newProcess.StandardOutput;
		output = outputStream.ReadToEnd();
	}
else
	{
		output = "Timed out at " + timeoutSeconds + " seconds waiting for " + exeName + " to exit.";
	}
}

catch(Exception e)
{
throw (new Exception("An error occurred running " + exeName + ".",e));
}
finally
{
outputStream.Close();
}

Return the output to the calling method:
```
return "\t" + output;
					
```
Save the file as Start.cs.

This sample code provides an efficient way to wrap any command-line utility. In the application that you are writing, call the Run method of the LaunchEXE class and pass it any executable program with the appropriate arguments and Timeout value, and then parse the results in your own application.

back to the top

Use the Wrapper in Your Application

To use the wrapper, you have to add the class file to a new application that will use this class. You can also use this class in any other Visual C# .NET application.

To integrate this class into your Visual Studio C# application:
1. Start Visual Studio.
2. Open the New Project dialog box. On the File menu, point to New, and then click Project.
3. Select Visual C# Projects and for a template, select Windows Application.
4. Type a name for your project in the Name text box, and then click OK. Visual Studio creates a new C# Windows application.
5. In Solution Explorer, right-click your project name, point to Add, and then click Existing item. The Add Existing Item dialog box opens in Visual Studio. To add the C# class file to your application, browse to the folder in which you stored Start.cs, right-click Start.cs, and then click Open.
To access the class in Start.cs from your application, make your class file a member of the namespace for your project:
1. In Solution Explorer, right-click the Form1.cs file that you created for your project, and then click View Code to open Form1.cs in the main window. At the top of the code file, you should see the word namespace, which is followed by your project name. Add this line in the same place in the Start.cs file.
2. In Solution Explorer, right-click Start.cs, and then click View Code.
3. Add the namespace line after the USING statements.
  
  Your code should now resemble the following sample (in this sample, the project name is WindowsApplication1):
```
using System;
using System.IO;
using System.Diagnostics;

namespace WindowsApplication1
{
	internal class LaunchEXE
	{
		internal static string Run(string exeName, string argsLine, int timeoutSeconds)
		{
        ...
					
```
Make the class file a member of the namespace to create a reference to your class file, and then call the Run method:
1. Click the Form1.cs [Design] tab to view your form.
2. Place a button on the form, and then call the Run method inside of the Click event for the button:
  1. On the View menu, click Toolbox.
  2. Drag a button control onto the form. Double-click the button to start the code editor in which Visual Studio has created an event handler that you use to place your code for the Click event for the button. It should be placed within a code section that resembles the following sample:
```
private void button1_Click(object sender, System.EventArgs e)
{
		
}
						
```
Add the following code to the event handler to call the Run function:
```
private void button1_Click(object sender, System.EventArgs e)
{
     string output;
     output = LaunchEXE.Run("CommandLineTool.exe", "arg1 arg2", 10);
     System.Windows.Forms.MessageBox.Show(output);
}
						
```
In the first line of this code, you declare a new variable, which is named output, that you use to store the result of the command-line tool. In the second line, you state that the output variable is equal to that which the Run method returns. On this line you also specify that you want to start CommandLineTool.exe (which you can replace with the name of your own command-line tool). You pass the command-line tool two arguments, arg1 and arg2 (which you can replace with the name of the arguments that you want to pass to your .exe program). The third argument, which is a value of 10, indicates that the command-line tool must complete within 10 seconds. The last line in this code sample creates a pop-up message in which the output from the command-line tool is displayed.
Press F5 to run the application.
Click the button on the form. Within 10 seconds, a pop-up message box should open and display the output from the command-line tool.

In a real application, you can parse the output that is returned from your command-line tool, and display it in a more friendly form to your users through the graphical user interface (GUI).

How To Write a Wrapper for a Command-Line Tool with Visual C# .NET (305994)

IN THIS TASK

SUMMARY

Build the Code for the Wrapper

Use the Wrapper in Your Application