Extending the Visual

Basic Application Model

 07/20/2015  4 minutes to read Contributors all

In this article
Visual Overview of the Application Model
Overriding the Base Methods
Configuring the Application
See Also

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.

Visual Overview of the Application

Model
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.
The Visual Basic Application Model also provides the
StartupNextInstance and UnhandledException events. The
following graphics show the mechanism for raising these
events.

Overriding the Base Methods

The Run method defines the order in which the Application
methods run. By default, the Sub Main procedure for a
Windows Forms application 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:

1. 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 ShowSplashScreen if neither
/nosplash nor -nosplash is 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:

a. 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.MinimumSplashScreenDisplayTime
property to two seconds), or set the
My.Application.MinimumSplashScreenDisplayTime

property in a method that overrides the OnInitialize or

OnCreateSplashScreen method. For more information,
see MinimumSplashScreenDisplayTime.

b. 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.

2. OnStartup. Provides an extensibility point for raising the

Startup event. The application startup sequence stops if
this function returns False .

By default, this method raises the Startup event. If the

event handler sets the Cancel property of the event
argument to True , the method returns False to
cancel the application startup.

3. 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:

a. 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.

b. 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.

 4. 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.

5. OnShutdown. Provides an extensibility point for raising

the Shutdown event. This method does not run if an
unhandled exception occurs in the main application.

By default, this method raises the Shutdown event.

6. 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 UnhandledException event.

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 OnStartupNextInstance(StartupNextInstanceEventArgs)
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.

Configuring the Application

As a part of the Visual Basic Application model, the
UseCompatibleTextRendering 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.

Setting in
the
Application
pane of the
Project
Property Determines Designer

IsSingleInstance Whether the Make

application runs as a single
single-instance or instance
multiple-instance application
application. check box

EnableVisualStyles If the application will Enable XP

use visual styles that visual styles
match Windows XP. check box

SaveMySettingsOnExit If application Save

automatically saves My.Settings
application's user- on
settings changes Shutdown
when the application check box
exits.

ShutdownStyle What causes the Shutdown

application to mode list
terminate, such as
when the startup form
closes or when the
last form closes.

See Also
ApplicationBase
Startup
StartupNextInstance
UnhandledException
Shutdown
NetworkAvailabilityChanged
NetworkAvailabilityChanged
Overview of the Visual Basic Application Model
Application Page, Project Designer (Visual Basic)