Shell

Class (inherits from Object)

Used to execute Unix or DOS shell commands under Windows, macOS, or Linux.

Events

Completed DataAvailable

Properties

Arguments ExecuteMode PID Backend ExitCode Result Canonical IsRunning TimeOut

Methods

Close Poll Write Execute ReadAll WriteLine

Enumerations

ExecuteModes

Notes

Use the Shell class to execute DOS or Unix commands and get the results. The Execute method executes a one-line command in Synchronous mode. This causes two properties of the Shell object to change: ErrorCode, which is a system-supplied error code or 0 for no error; and Result, which is a string containing the output of the command. The TimeOut property specifies how long (in milliseconds) a process can run before it is automatically terminated. A value of -1 means the process can run indefinitely. This property currently applies only to Windows.

The process running in the Shell is killed when the object gets out of scope even if running in asynchronous or interactive modes.

The Shell is not equivalent to the Terminal or Command app for your OS. Paths and other default settings will likely not be the same. If you need to do configuration of the Shell before you use it, be sure to set it up to be interactive so you can set up the configuration before calling other shell commands. Alternatively you could create a batch file that sets everything up and call that instead.

If you send a unavailable command to the Shell, a ShellNotAvailableException will be raised.

Shell Differences on Windows

It appears that some Windows shell commands such as ftp or telnet will not work as expected due to these tools not using the standard IO streams that can be read by the Shell class.

Some workarounds:

• Take advantage of the ftp commands built-in scripting capability.
• Spawn the ftp app in a hidden console window and read its input using low-level console IO functions as described in this Microsoft document: http://msdn.microsoft.com/en-us/library/ms684965(VS.85).aspx
• Use a 3rd part ftp or telnet class.

Sample Code

Using the synchronous mode, the following code lists the current directory's files using the dir command on Windows and ls on macOS and Linux.

Var s As Shell
s = New Shell
#If TargetWindows Then
s.Execute("dir")
#ElseIf TargetMacOS Or TargetLinux Then
s.Execute("ls -la")
#Endif
If s.ExitCode = 0 Then
TextField1.Text= s.Result
Else
MessageBox("Error code: " + s.ErrorCode.ToString)
End If

The following example gets the names and values of the environment variables on the user's computer and displays the information in a TextField. You can use the EnvironmentVariable method of the System module to get or set individual environment variables.

Var s As New Shell
Var cmd As String
#If TargetMacOS Or TargetLinux Then
cmd = "env"
#ElseIf TargetWindows Then
cmd = "set"
#Endif
s.Execute(cmd)
If s.ExitCode = 0 Then
TextField1.Text = s.Result
Else
TextField1.Text = "Error " + Str(s.ErrorCode)
End If

Interactive Shells

The following terminal application allows you to submit Unix commands using the interactive mode. The interface consists of two TextFields, InputField, in which the user can enter a command, and OutputField that displays the results.

The Open event for the window initializes the shell object (declared as a property of the window).

mShell = New Shell
mShell.ExecuteMode = Shell.ExecuteModes.Interactive

The user can type a unix command into the TextField, InputField. When he presses Return, the following code in the TextField's KeyDown event runs. The Write method sends the command to the Shell's input buffer.

If key = Chr(13) Then
If Not mShell.IsRunning Then
mShell.Execute("sh")
End If
mShell.Write(InputField.Text)
mShell.Write(Chr(13))
InputField.Text = ""
Return True
Else
Return False
End If

A Timer calls the ReadAll method in its Action event and displays the output in OutputField:

If mShell <> Nil Then
Var output As String = mShell.ReadAll
If output <> "" Then
OutputField.SelectedText = output
End If
End If

See Also

TargetLinux, TargetMachO, TargetMacOS, TargetWindows, TargetX86 constants.