Recipe 14.1. Preventing Multiple Instances of a Running Application

Problem

You don't want the active user to run more than one copy of an application at any one time.

Solution

Sample code folder: Chapter 14\SingleInstanceOnly

Capture attempts to start up secondary instances of an application through an application-wide event handler. This event handler, new to Visual Basic 2005 and available only to Windows Forms applications using the Application Framework, triggers in the primary instance whenever the user tries to start a secondary instance.

Discussion

Create a new Windows Forms application in Visual Studio. The Application Framework is enabled by default; you can confirm this by checking the "Enable application framework" field on the Application tab of the Project Properties window, shown in Figure 14-1.

Figure 14-1. Make sure the "Enable application framework" field is checked

Even with the Application Framework enabled, by default the application allows multiple instances to start at once. To prevent this, select the "Make single instance application" field on this same Project Properties panel (Figure 14-1 still shows it as unchecked).

The event to handle is typically called MyApplication_StartupNextInstance, and it appears by default in the project's ApplicationEvents.vb file. Since you already have the Application panel of the Project Properties window open, you can access this file quickly by clicking on the View Application Events button. The source code appears, with the start of a partial My.MyApplication class:

 Namespace My    Partial Friend Class MyApplication    End Class End Namespace 

To add the event handler, select "(MyApplication Events)" from the Class Name drop-down list, which appears just above and to the left of the source code editor window. Then select "StartupNextInstance" from the Method Name drop-down list that is above and to the right of the code editor. The template for the event handler appears in the MyApplication class:

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

To complete the program, add the following code to this template:

 MsgBox("You cannot start a second instance " & _    "of this program.", _    MsgBoxStyle.OkOnly Or MsgBoxStyle.Exclamation) e.BringToForeground = True 

Even if you limit your application to a single instance, it may be important to capture any command-line arguments supplied with the secondary instance. For example, Microsoft Word works like a single-instance application. It allows you to start up the application, supplying a document to edit as a command-line argument. If you run this command in Microsoft Word:

 winword.exe C:\Chapter14.doc 

the Chapter14.doc file appears as a new document, but running in the context of the already active single allowable instance of Microsoft Word.

In Visual Basic, you can access command-line arguments through the Command() function or through the My.Application.CommandLineArgs collection. However, these methods are valid only for the primary instance. If you examine Command() in the MyApplication_StartupNextInstance event handler, you will only see the arguments for the initial instance.

Fortunately, the e argument of the MyApplication_StartupNextInstance handler includes a CommandLine property, which communicates the command-line arguments for the subsequent instance as a String. Use this property as you would the return value of the standard Command() function. Once the event handler ends, you won't have access to the second instance's command line, so make sure you examine or save it, if needed, while in the handler.