Overview of the Visual Basic Application Model
Updated: July 20, 2015
For the latest documentation on Visual Studio 2017 RC, see Visual Studio 2017 RC Documentation.
Visual Basic provides a well-defined model for controlling the behavior of Windows Forms applications: the Visual Basic Application model. This model includes events for handling the application's startup and shutdown, as well as events for catching unhandled exceptions. It also provides support for developing single-instance applications. The application model is extensible, so developers that need more control can customize its overridable methods.
A typical application needs to perform tasks when it starts up and shuts down. For example, when it starts up, the application can display a splash screen, make database connections, load a saved state, and so on. When the application shuts down, it can close database connections, save the current state, and so on. In addition, the application can execute specific code when the application shuts down unexpectedly, such as during an unhandled exception.
The Visual Basic Application model makes it easy to create a single-instance application. A single-instance application differs from a normal application in that only one instance of the application can be running at a time. An attempt to launch another instance of a single-instance application results in the original instance being notified—by means of the
StartupNextInstance event—that another launch attempt was made. The notification includes the subsequent instance's command-line arguments. The subsequent instance of the application is then closed before any initialization can occur.
A single-instance application starts and checks whether it is the first instance or a subsequent instance of the application:
If it is the first instance, it starts as usual.
Each subsequent attempt to start the application, while the first instance runs, results in very different behavior. The subsequent attempt notifies the first instance about the command-line arguments, and then immediately exits. The first instance handles the
StartupNextInstanceevent to determine what the subsequent instance's command-line arguments were, and continues to run.
This diagram shows how a subsequent instance signals the first instance.
By handling the
StartupNextInstance event, you can control how your single-instance application behaves. For example, Microsoft Outlook typically runs as a single-instance application; when Outlook is running and you attempt to start Outlook again, focus shifts to the original instance but another instance does not open.
The following events are found in the application model:
Application startup. The application raises the Startup event when it starts. By handling this event, you can add code that initializes the application before the main form is loaded. The
Startupevent also provides for canceling execution of the application during that phase of the startup process, if desired.
You can configure the application to show a splash screen while the application startup code runs. By default, the application model suppresses the splash screen when either the
-nosplashcommand-line argument is used.
Single-instance applications. The StartupNextInstance event is raised when a subsequent instance of a single-instance application starts. The event passes the command-line arguments of the subsequent instance.
Unhandled exceptions. If the application encounters an unhandled exception, it raises the UnhandledException event. Your handler for that event can examine the exception and determine whether to continue execution.
UnhandledExceptionevent is not raised in some circumstances. For more information, see UnhandledException.
Network-connectivity changes. If the computer's network availability changes, the application raises the NetworkAvailabilityChanged event.
NetworkAvailabilityChangedevent is not raised in some circumstances. For more information, see NetworkAvailabilityChanged.
Application shut down. The application provides the Shutdown event to signal when it is about to shut down. In that event handler, you can make sure that the operations your application needs to perform—closing and saving, for example—are completed. You can configure your application to shut down when the main form closes, or to shut down only when all forms close.
By default, the Visual Basic Application model is available for Windows Forms projects. If you configure the application to use a different startup object, or start the application code with a custom
Sub Main, then that object or class may need to provide an implementation of the WindowsFormsApplicationBase class to use the application model. For information about changing the startup object, see Application Page, Project Designer (Visual Basic).