Shell Function

Runs an executable program and returns an integer containing the program's process ID if it is still running.

Public Function Shell( _
   ByVal PathName As String, _ 
   Optional ByVal Style As AppWinStyle = AppWinStyle.MinimizedFocus, _ 
   Optional ByVal Wait As Boolean = False, _ 
   Optional ByVal Timeout As Integer = -1 _
) As Integer

Parameters

  • PathName
    Required. String. Name of the program to execute, together with any required arguments and command-line switches. PathName can also include the drive and the directory path or folder.

    If you do not know the path to the program, you can use the My.Computer.FileSystem.GetFiles Method to locate it. For example, you can call My.Computer.FileSystem.GetFiles("C:\", True, "testFile.txt"), which returns the full path of every file named testFile.txt anywhere on drive C:\.

  • Style
    Optional. AppWinStyle. A value chosen from the AppWinStyle Enumeration specifying the style of the window in which the program is to run. If Style is omitted, Shell uses AppWinStyle.MinimizedFocus, which starts the program minimized and with focus.

  • Wait
    Optional. Boolean. A value indicating whether the Shell function should wait for completion of the program. If Wait is omitted, Shell uses False.

  • Timeout
    Optional. Integer. The number of milliseconds to wait for completion if Wait is True. If Timeout is omitted, Shell uses -1, which means there is no timeout and Shell does not return until the program finishes. Therefore, if you omit Timeout or set it to -1, it is possible that Shell might never return control to your program.

Exceptions

Exception type

Error number

Condition

ArgumentException

5

Style is not within range 0 through 9, inclusive.

FileNotFoundException

53

Shell cannot find the PathName file.

NullReferenceException

91

PathName is Nothing.

See the "Error number" column if you are upgrading Visual Basic 6.0 applications that use unstructured error handling. (You can compare the error number against the Number Property (Err Object).) However, when possible, you should consider replacing such error control with Structured Exception Handling Overview for Visual Basic.

Remarks

The return value of the Shell function depends on whether the program named in PathName is still executing when Shell returns. If you set Wait to True and the program finishes before the timeout expires, Shell returns zero. If the timeout expires, or if you omit Wait or set it to False, Shell returns the process ID of the program. The process ID is a unique number that identifies the running program.

Failure to Start

If the Shell function cannot start the named program, a FileNotFoundException error occurs. This can happen, for example, when you attempt to run a 16-bit program, such as command.com, from an application using System.Windows.Forms. For a workaround, you can run a 32-bit program that calls the desired 16-bit program. In the case of command.com, you can run cmd.exe as an alternative.

Waiting for Completion

By default, the Shell function runs the program asynchronously. This means that a program that starts with the Shell function might not finish executing before the statements that follow the Shell function execute. If you want to wait for the program to finish before you continue, set Wait to True.

Determining the Exit Code

A process can return an exit code when it terminates. However, you cannot use Shell to retrieve this exit code, because Shell returns zero if it waits for termination, and also because the process runs in a different object from Shell.

To retrieve the exit code from a process, you must write your own code to initiate the process and wait for termination. The following example shows how to initiate a process, wait for it to terminate, and retrieve its exit code.

Dim procID As Integer
Dim newProc As Diagnostics.Process
newProc = Diagnostics.Process.Start("C:\WINDOWS\NOTEPAD.EXE")
procID = newProc.Id
newProc.WaitForExit()
Dim procEC As Integer = -1
If newProc.HasExited Then
    procEC = newProc.ExitCode
End If
MsgBox("Process with ID " & CStr(ProcID) & _
    " terminated with exit code " & CStr(procEC))

Protecting the File Specification

You should always enclose the entire path and file specification in quotation marks, as the following example shows.

ID = Shell("""C:\Program Files\display.exe"" -a -q", , True, 100000)

Each pair of adjacent double quotation marks (" ") within the string literal is interpreted as one double quotation character in the string. Therefore, the preceding example presents the following string to the Shell function:

"C:\Program Files\display.exe" -a -q

If the path is not enclosed in quotation marks, Windows looks for a file called Program.exe in the C:\ directory, instead of display.exe in the C:\Program Files directory.

Security noteSecurity Note:

If you do not enclose the path and file specification in quotation marks, there is a security risk if the file name or a path node contains spaces. In the preceding example, the path node \Program Files includes a space. If the specification is not located inside quotation marks and a program named Program.exe is installed in C:\, for example by illicit tampering, Windows executes it instead of display.exe.

Security noteSecurity Note:

The Shell function requires unmanaged code permission, which might affect its execution in partial-trust situations. For more information, see SecurityPermission and Code Access Permissions.

Example

The following example uses the Shell function to run an application specified by the user. Specifying AppWinStyle.NormalFocus as the second argument opens the application in normal size and gives it the focus.

Dim procID As Integer 
' Run calculator.
procID = Shell("C:\Windows\system32\calc.exe", AppWinStyle.NormalFocus)
' The preceding path is for Windows XP. 
' The Windows 2000 path is C:\WINNT\system32\calc.exe.

Smart Device Developer Notes

This function is not supported.

Requirements

Namespace: Microsoft.VisualBasic

Module: Interaction

Assembly: Visual Basic Runtime Library (in Microsoft.VisualBasic.dll)

See Also

Reference

AppWinStyle Enumeration

ArgumentException

FileNotFoundException

NullReferenceException

My.Computer.FileSystem.GetFiles Method

AppActivate Function