I wrote an article  for Coding4Fun on extending the My namespace so that you can program the LEGO Mindstorm robots.  Whether you are actually interested in programming LEGO robots with the My namespace or not (it is actually pretty fun :-) it is another example of how you can go about extending the My namespace. 

A question was posted on a MSDN VB forum about how to get single-instance behavior in a Whidbey app when your startup object isn't a form.  The IDE application designer doesn't accommodate this scenario.  But you can get single-instance behavior in situations like this by writing against the application model base class yourself.

Here's an example of a VB8 (Whidbey) console application that exhibits single-instance behavior:

Option Explicit On
Option Strict On

Module Module1
    Sub Main(ByVal args() As String)
        Dim App As New Application
        App.Run(args) 'passing args in enables App.CommandLineArgs
    End Sub
End Module

Class Application
    Inherits Microsoft.VisualBasic.ApplicationServices.WindowsFormsApplicationBase

    Sub New()
        'If you are setting your own custom principal instead of using
        'the windows principal, pass AuthenticationMode.ApplicationDefined
        'so we don't run it over in the ctor.  The default ctor puts the
        'windows principal on the main thread.
        MyBase.New()
        Me.IsSingleInstance = True 'Turns on the single-instance behavior
    End Sub

    Protected Overrides Sub OnRun()'Put your code that you'd have place in Main(), here.
        Console.WriteLine("Running as " & My.User.Name & ". Press a key to exit") 
        While Not System.Console.KeyAvailable
            DoEvents() 'pumps messages so StartupNextInstance() gets called
        End While
    End Sub

    Private Sub MyApplication_StartupNextInstance(ByVal sender As Object, _
        ByVal e As Microsoft.VisualBasic.ApplicationServices.StartupNextInstanceEventArgs) _ 
        Handles Me.StartupNextInstance
       
        MsgBox("An attempt to launch an additional instance was made.")
    End Sub
End Class

When you first run this app you'll get the message that it is running and it will just hang out waiting for a key press.  If you launch it again while the first instance is still running, the first instance will display the dialog about an attempt to launch another instance.  The subsequent attempt to launch will just return without launching a new instance.  You now have a single-instance console application.

I am utilizing the single-instance behavior logic which lives in the Microsoft.VisualBasic.ApplicationServices.WindowsFormsApplicationBase class.  Note that in the ctor for Application that I call MyBase.New() without any arguments.  This will result in the windows principal being put on the main thread.  My.User will then reflect the windows account that is running this app.  If you are setting your own custom principal, pass in AuthenticationMode.ApplicationDefined instead so that your principal doesn't get run over when the class initializes.

I use Main() simply to create my application object and start it up.  I put my startup logic, i.e. the code that would traditionally be in Main(), inside Application.OnRun(). 

You'll notice that I'm pumping events in OnRun().  Pumping events is only necessary if you want to use the application model events, such as StartupNextInstance().  WindowsApplicationBase uses the message pump to marshal events onto the main thread.  So if you aren't yielding control to windows you'll need to pump messages in your app if you want the app model events.  If you don't care about handling the application model events then you can safely ignore that part.

Note that you also get access to the other application model events such as the Shutdown event.  You won't get the UnhandledException() event because it isn't getting hooked up.  Getting that to work is a subject for another post someday if there is interest in that.

By the way, if you are curious you can see the code generated by the IDE for Windows Forms apps.  Just create a windows forms app, turn on single-instance in the application page of the project designer, turn on 'view all files' in the solution explorer, and then look at the hidden file Application.Designer.vb which is under the MyProject/Application.MyApp node.

So what's a Single-Instance application?  Imagine launching an application where additional attempts to launch the app while the first one is running doesn't actually launch a new instance of the app.  Instead the original instance of the app gets notified that another launch attempt occurred.  When we introduced an application model for Visual Basic in VB 2005, one of the things we wanted to do is make it drop-dead easy to create single-instance applications.

It's easier to understand single-instance apps with an example.  I don't know for certain that Word is a single-instance app but it seems to behave like one.  If you crank up the task manager and launch Word you'll see WinWord.exe show up.  But if you launch it again while an instance of Word is already running, you won't see another WinWord.exe show up in the task manager.  You can see the memory footprint of Word go up but it only goes up a little.  I assume that is memory needed just for the new document.  How Word manages its single-instance behavior is frankly not something I know anything about so I'm only guessing at what it is doing based on watching the task manager.  But it has the tale-tale signs of a single-instance app.

Single-Instance apps are useful in situations where you don't want to have multiple instances of the app running.  Maybe you can only have one running on the machine at any given time.  Or maybe you have a scenario where you have an app that can manage multiple documents.  In that case a single-instance app would provide a nice way to avoid loading multiple copies of your exe just to manage one more document.  Instead, the currently running app could just be told to load another document. Less memory consumption, faster subsequent document load times.  It's goodness.

You can find code samples on the internet to create single-instance apps.  Previously you had to hunt down the code, wire it into your own startup code, and then decide whether it used a technique that you think is robust enough or secure enough for your purposes.  We decided we wanted to provide a robust/secure single-instance capability that you could just turn on by clicking on a checkbox.  This switch lives on the application page in the project designer under Windows application framework properties and is called:  Make single instance application.  That's a lot of intro for the issue I want to talk about.''

One of the questions that comes up is: So how do we determine whether a subsequent instance of an application has launched?  Do we key off of the path where the app was launched from, or what?

We don't key off of the path where the app was launched from.  Single-Instance apps have a single-instance application identity.   When a single-instance app launches, it checks to see if an app with the same identity is already running.  If it is, we call that app's StartupNextInstance() event (which will be raised on the main thread of the original instance) and pass it the command line.  The subsequent instance then just exits; leaving the original instance to decide what it wants to do about the fact that somebody tried to launch another instance of itself.  A common thing to do would be to examine the command line passed into the StartupNextInstance() event and try to load the document specified.

What does this single-instance application identity look like?  It is comprised of the assembly guid and the assembly (not file) major and minor version number.  You can see the assembly guid and assembly version information by selecting the Assembly Information button on the application page in the project designer.  Taken together these three pieces of information identify the identity of the single-instance application.

There are some ramifications from all of this.  Different versions of an application won't act as single instances against each other.  For instance, if you launch version 1.0 of Foo.exe, and then launch version 1.1 of Foo.exe, you won't get the single instance behavior.  You'll have two versions of foo.exe running.

If you have two copies of foo.exe on the machine in c:\foo1 and c:\foo2, and then launch c:\foo1\foo.exe followed by c:\foo2\foo.exe, you will get single-instance behavior between the two.  That is, you'll only get one instance of foo.exe running, the one in c:\foo1\foo.exe.  Launching c:\foo2\foo.exe will simply raise the event on the first and then terminate.  The application startup directory is not part of the single-instance application identity so it has no bearing on whether an application thinks another instance of itself is already running.

This means that you can't easily contrive a situation where c:\foo1\foo.exe only exhibits single instance behavior when foo.exe is launched from c:\foo1 instead of c:\foo2 merely because they are in different directories.  If you wanted c:\foo2\foo.exe to be considered a different app then c:\foo1\foo.exe, you'd have to differentiate the two foo.exes by either changing the assembly version number or assembly guid of one of them.

Currently there is no user facing way of setting the single-instance identity.  In practice do people find that this is terribly limiting?