Recipe 2.9. Getting an Application s Command Line

Recipe 2.9. Getting an Application's Command Line

Problem

You've designed your program to support optional command-line arguments, and you want to process them.

Solution

There are a few different ways to examine and process the command-line options supplied to your program. The first and easiest of the methods involves the Visual Basic Command() function, part of the Microsoft.VisualBasic namespace. This function returns the entire set of command-line options as a String. For instance, if the user enters the following command:

 MyApp.exe /option1 /option2 filename.txt 

the Command( ) function returns:

 /option1 /option2 filename.txt 

The application name and extension are always removed from the string; Command( ) returns only the options, not the program name.

Because Command() returns a single string with the entire command-line option text, the responsibility for parsing each option from the string rests on your shoulders. However, Visual Basic also supplies a pre-parsed version of the options through the My.Application.CommandLineArgs collection. Each zero-based argument in the collection includes one of the original space-delimited options as entered by the user. Thus, using the example command line from just a few paragraphs ago, the following method call:

 MsgBox(My.Application.CommandLineArgs(1)) 

displays /option2, because the collection is zero-based.

Discussion

Many applications support optional command-line arguments, generally to alter the initial view of the application on startup. Normally such arguments are entered through the Windows command prompt, cmd.exe. For example, the Notepad.exe program accepts a single command-line argument, a filename to open immediately:

 Notepad.exe c:\temp\DataFile.txt 

Windows does provide some support for command-line option usage. If you create a shortcut to an application, the Target field in the shortcut's properties (accessed by right-clicking on the shortcut icon and selecting Properties) will accept commandline arguments after the executable name.

If you use the Windows File Explorer to drag and drop a file onto an application (EXE) icon, Windows starts the application, adding the dropped file's name as a command-line argument.

No matter which method you use to add command-line arguments to your application, they are received through the Command() and My.Application.CommandLineArgs features of Visual Basic.

There is one exception to this general rule. Visual Basic applications can be configured as "single-instance" applications by selecting the " Make single instance application" field on the Application tab of the Project Properties window. If a user tries to start a second instance of a single-instance application when an instance is already running, the second instance will not run. Instead, a special event triggers in the first instance, informing the program that the user wants to start a new instance. It is up to the program to determine how to handle such requests. The Command() and CommandLineArgs features indicate only the options for the initial instance of a single-instance program; command-line arguments for subsequent instances are processed as part of the arguments to the special additional-instance event.

To use this special StartupNextInstance event:

1. Access the Application tab of the Project Properties window.

2. Click on the View Application Events button on that tab to display the source code from the ApplicationEvents.vb file.

3. Select "(MyApplication Events)" from the Class Name list that is above and to the left of the code window.

4. Select "StartupNextInstance" from the Method Name list just to the right of the Class Name list.

The following code fragment appears:

 Private Sub MyApplication_StartupNextInstance( _       ByVal sender As Object, ByVal e As _       Microsoft.VisualBasic.ApplicationServices. _       StartupNextInstanceEventArgs) _       Handles Me.StartupNextInstance End Sub 

The e argument includes a CommandLine collection member that works just like the My.Application.CommandLineArgs collection but is specific to the new instance requested by the user.