Extending the Visual Basic Application Model
Updated: July 20, 2015
For the latest documentation on Visual Studio 2017 RC, see Visual Studio 2017 RC Documentation.
You can add functionality to the application model by overriding the
Overridable members of the WindowsFormsApplicationBase class. This technique allows you to customize the behavior of the application model and add calls to your own methods as the application starts up and shuts down.
This section visually presents the sequence of function calls in the Visual Basic Application Model. The next section describes the purpose of each function in detail.
The following graphic shows the application model call sequence in a normal Visual Basic Windows Forms application. The sequence starts when the
Sub Main procedure calls the Run method.
If the application is a normal application (multiple-instance application), or the first instance of a single-instance application, the Run method executes the
Overridable methods in the following order:
OnInitialize. By default, this method sets the visual styles, text display styles, and current principal for the main application thread (if the application uses Windows authentication), and calls
-nosplashis used as a command-line argument.
The application startup sequence is canceled if this function returns
False. This can be useful if there are circumstances in which the application should not run.
The OnInitialize method calls the following methods:
ShowSplashScreen. Determines if the application has a splash screen defined and if it does, displays the splash screen on a separate thread.
The ShowSplashScreen method contains the code that displays the splash screen for at least the number of milliseconds specified by the MinimumSplashScreenDisplayTime property. To use this functionality, you must add the splash screen to your application using the Project Designer (which sets the
My.Application.MinimumSplashScreenDisplayTimeproperty to two seconds), or set the
My.Application.MinimumSplashScreenDisplayTimeproperty in a method that overrides the OnInitialize or OnCreateSplashScreen method. For more information, see MinimumSplashScreenDisplayTime.
OnCreateSplashScreen. Allows a designer to emit code that initializes the splash screen.
By default, this method does nothing. If you select a splash screen for your application in the Visual Basic Project Designer, the designer overrides the OnCreateSplashScreen method with a method that sets the SplashScreen property to a new instance of the splash-screen form.
OnStartup. Provides an extensibility point for raising the
Startupevent. The application startup sequence stops if this function returns
OnRun. Provides the starting point for when the main application is ready to start running, after the initialization is done.
By default, before it enters the Windows Forms message loop, this method calls the
OnCreateMainForm(to create the application's main form) and
HideSplashScreen(to close the splash screen) methods:
OnCreateMainForm. Provides a way for a designer to emit code that initializes the main form.
By default, this method does nothing. However, when you select a main form for your application in the Visual Basic Project Designer, the designer overrides the OnCreateMainForm method with a method that sets the MainForm property to a new instance of the main form.
HideSplashScreen. If application has a splash screen defined and it is open, this method closes the splash screen.
By default, this method closes the splash screen.
OnStartupNextInstance. Provides a way to customize how a single-instance application behaves when another instance of the application starts.
By default, this method raises the StartupNextInstance event.
OnShutdown. Provides an extensibility point for raising the
Shutdownevent. This method does not run if an unhandled exception occurs in the main application.
By default, this method raises the Shutdown event.
OnUnhandledException. Executed if an unhandled exception occurs in any of the above listed methods.
By default, this method raises the UnhandledException event as long as a debugger is not attached and the application is handling the
If the application is a single-instance application, and the application is already running, the subsequent instance of the application calls the OnStartupNextInstance method on the original instance of the application, and then exits.
The WindowsFormsApplicationBase constructor calls the UseCompatibleTextRendering property to determine which text rendering engine to use for the application's forms. By default, the UseCompatibleTextRendering property returns
False, indicating that the GDI text rendering engine be used, which is the default in Visual Basic 2005. You can override the UseCompatibleTextRendering property to return
True, which indicates that the GDI+ text rendering engine be used, which is the default in Visual Basic .NET 2002 and Visual Basic .NET 2003.
As a part of the Visual Basic Application model, the WindowsFormsApplicationBase class provides protected properties that configure the application. These properties should be set in the constructor of the implementing class.
In a default Windows Forms project, the Project Designer creates code to set the properties with the designer settings. The properties are used only when the application is starting; setting them after the application starts has no effect.
|Property||Determines||Setting in the Application pane of the Project Designer|
|IsSingleInstance||Whether the application runs as a single-instance or multiple-instance application.||Make single instance application check box|
|EnableVisualStyles||If the application will use visual styles that match Windows XP.||Enable XP visual styles check box|
|SaveMySettingsOnExit||If application automatically saves application's user-settings changes when the application exits.||Save My.Settings on Shutdown check box|
|ShutdownStyle||What causes the application to terminate, such as when the startup form closes or when the last form closes.||Shutdown mode list|
Overview of the Visual Basic Application Model
Application Page, Project Designer (Visual Basic)