Object lifetime events (WPF .NET)

Article
10/24/2024

During their lifetime, all objects in Microsoft .NET managed code go through creation, use, and destruction stages. Windows Presentation Foundation (WPF) provides notification of these stages, as they occur on an object, by raising lifetime events. For WPF framework-level elements (visual objects), WPF implements the Initialized, Loaded, and Unloaded lifetime events. Developers can use these lifetime events as hooks for code-behind operations that involve elements. This article describes the lifetime events for visual objects, and then introduces other lifetime events that specifically apply to window elements, navigation hosts, or application objects.

Prerequisites

This article assumes a basic knowledge of how WPF element layout can be conceptualized as a tree, and that you've read Routed events overview. To follow the examples in this article, it helps if you're familiar with Extensible Application Markup Language (XAML) and know how to write WPF applications.

Lifetime events for visual objects

WPF framework-level elements derive from FrameworkElement or FrameworkContentElement. The Initialized, Loaded, and Unloaded lifetime events are common to all WPF framework-level elements. The following example shows an element tree that's primarily implemented in XAML. The XAML defines a parent Canvas element that contains nested elements, which each use XAML attribute syntax to attach Initialized, Loaded, and Unloaded lifetime event handlers.

<Canvas x:Name="canvas">
    <StackPanel x:Name="outerStackPanel" Initialized="InitHandler" Loaded="LoadHandler" Unloaded="UnloadHandler">
        <custom:ComponentWrapper x:Name="componentWrapper" Initialized="InitHandler" Loaded="LoadHandler" Unloaded="UnloadHandler">
            <TextBox Name="textBox1" Initialized="InitHandler" Loaded="LoadHandler" Unloaded="UnloadHandler" />
            <TextBox Name="textBox2" Initialized="InitHandler" Loaded="LoadHandler" Unloaded="UnloadHandler" />
        </custom:ComponentWrapper>
    </StackPanel>
    <Button Content="Remove canvas child elements" Click="Button_Click"/>
</Canvas>

One of the XAML elements is a custom control, which derives from a base class that assigns lifetime event handlers in code-behind.

public partial class MainWindow : Window
{
    public MainWindow() => InitializeComponent();

    // Handler for the Initialized lifetime event (attached in XAML).
    private void InitHandler(object sender, System.EventArgs e) => 
        Debug.WriteLine($"Initialized event on {((FrameworkElement)sender).Name}.");

    // Handler for the Loaded lifetime event (attached in XAML).
    private void LoadHandler(object sender, RoutedEventArgs e) => 
        Debug.WriteLine($"Loaded event on {((FrameworkElement)sender).Name}.");

    // Handler for the Unloaded lifetime event (attached in XAML).
    private void UnloadHandler(object sender, RoutedEventArgs e) =>
        Debug.WriteLine($"Unloaded event on {((FrameworkElement)sender).Name}.");

    // Remove nested controls.
    private void Button_Click(object sender, RoutedEventArgs e) => 
        canvas.Children.Clear();
}

// Custom control.
public class ComponentWrapper : ComponentWrapperBase { }

// Custom base control.
public class ComponentWrapperBase : StackPanel
{
    public ComponentWrapperBase()
    {
        // Assign handler for the Initialized lifetime event (attached in code-behind).
        Initialized += (object sender, System.EventArgs e) => 
            Debug.WriteLine($"Initialized event on componentWrapperBase.");

        // Assign handler for the Loaded lifetime event (attached in code-behind).
        Loaded += (object sender, RoutedEventArgs e) => 
            Debug.WriteLine($"Loaded event on componentWrapperBase.");

        // Assign handler for the Unloaded lifetime event (attached in code-behind).
        Unloaded += (object sender, RoutedEventArgs e) => 
            Debug.WriteLine($"Unloaded event on componentWrapperBase.");
    }
}

/* Output:
Initialized event on textBox1.
Initialized event on textBox2.
Initialized event on componentWrapperBase.
Initialized event on componentWrapper.
Initialized event on outerStackPanel.

Loaded event on outerStackPanel.
Loaded event on componentWrapperBase.
Loaded event on componentWrapper.
Loaded event on textBox1.
Loaded event on textBox2.

Unloaded event on outerStackPanel.
Unloaded event on componentWrapperBase.
Unloaded event on componentWrapper.
Unloaded event on textBox1.
Unloaded event on textBox2.
*/

Partial Public Class MainWindow
    Inherits Window

    Public Sub New()
        InitializeComponent()
    End Sub

    ' Handler for the Initialized lifetime event (attached in XAML).
    Private Sub InitHandler(sender As Object, e As EventArgs)
        Debug.WriteLine($"Initialized event on {CType(sender, FrameworkElement).Name}.")
    End Sub

    ' Handler for the Loaded lifetime event (attached in XAML).
    Private Sub LoadHandler(sender As Object, e As RoutedEventArgs)
        Debug.WriteLine($"Loaded event on {CType(sender, FrameworkElement).Name}.")
    End Sub

    ' Handler for the Unloaded lifetime event (attached in XAML).
    Private Sub UnloadHandler(sender As Object, e As RoutedEventArgs)
        Debug.WriteLine($"Unloaded event on {CType(sender, FrameworkElement).Name}.")
    End Sub

    Private Sub Button_Click(sender As Object, e As RoutedEventArgs)
        ' Remove nested controls.
        canvas.Children.Clear()
    End Sub
End Class

' Custom control.
Public Class ComponentWrapper
    Inherits ComponentWrapperBase
End Class

' Custom base control.
Public Class ComponentWrapperBase
    Inherits StackPanel

    Public Sub New()
        ' Attach handlers for the lifetime events.
        AddHandler Initialized, AddressOf InitHandler
        AddHandler Loaded, AddressOf LoadHandler
        AddHandler Unloaded, AddressOf UnloadHandler
    End Sub

    ' Handler for the Initialized lifetime event (attached in code-behind).
    Private Sub InitHandler(sender As Object, e As EventArgs)
        Debug.WriteLine("Initialized event on componentWrapperBase.")
    End Sub

    ' Handler for the Loaded lifetime event (attached in code-behind).
    Private Sub LoadHandler(sender As Object, e As RoutedEventArgs)
        Debug.WriteLine("Loaded event on componentWrapperBase.")
    End Sub

    ' Handler for the Unloaded lifetime event (attached in code-behind).
    Private Sub UnloadHandler(sender As Object, e As RoutedEventArgs)
        Debug.WriteLine("Unloaded event on componentWrapperBase.")
    End Sub
End Class

'Output:
'Initialized event on textBox1.
'Initialized event on textBox2.
'Initialized event on componentWrapperBase.
'Initialized event on componentWrapper.
'Initialized event on outerStackPanel.

'Loaded event on outerStackPanel.
'Loaded event on componentWrapperBase.
'Loaded event on componentWrapper.
'Loaded event on textBox1.
'Loaded event on textBox2.

'Unloaded event on outerStackPanel.
'Unloaded event on componentWrapperBase.
'Unloaded event on componentWrapper.
'Unloaded event on textBox1.
'Unloaded event on textBox2.

The program output shows the order of invocation of Initialized, Loaded, and Unloaded lifetime events on each tree object. Those events are described in the following sections, in the order that they're raised on each tree object.

Initialized lifetime event

The WPF event system raises the Initialized event on an element:

When the properties of the element are set.
Around the same time that the object is initialized through a call to its constructor.

Some element properties, such as Panel.Children, can contain child elements. Parent elements can't report initialization until their child elements are initialized. So, property values are set starting with the most deeply nested element(s) in an element tree, followed by successive parent elements up to the application root. Since the Initialized event occurs when an element's properties are set, that event is first invoked on the most deeply nested element(s) as defined in markup, followed by successive parent elements up to the application root. When objects are dynamically created in code-behind, their initialization may be out of sequence.

The WPF event system doesn't wait for all elements in an element tree to be initialized before raising the Initialized event on an element. So, when you write an Initialized event handler for any element, keep in mind that surrounding elements in the logical or visual tree, particularly parent elements, may not have been created. Or, their member variables and data bindings might be uninitialized.

Note

When the Initialized event is raised on an element, the element's expression usages, such as dynamic resources or binding, will be unevaluated.

Loaded lifetime event

The WPF event system raises the Loaded event on an element:

When the logical tree that contains the element is complete and connected to a presentation source. The presentation source provides the window handle (HWND) and rendering surface.
When data binding to local sources, such as other properties or directly defined data sources, is complete.
After the layout system has calculated all necessary values for rendering.
Before final rendering.

The Loaded event isn't raised on any element in an element tree until all elements within the logical tree are loaded. The WPF event system first raises the Loaded event on the root element of an element tree, then on each successive child element down to the most deeply nested element(s). Although this event might resemble a tunneling routed event, the Loaded event doesn't carry event data from one element to another, so marking the event as handled has no effect.

Note

The WPF event system can't guarantee that asynchronous data bindings have completed before the Loaded event. Asynchronous data bindings bind to external or dynamic sources.

Unloaded lifetime event

The WPF event system raises the Unloaded event on an element:

On removal of its presentation source, or
On removal of its visual parent.

The WPF event system first raises the Unloaded event on the root element of an element tree, then on each successive child element down to the most deeply nested element(s). Although this event might resemble a tunneling routed event, the Unloaded event doesn't propagate event data from element to element, so marking the event as handled has no effect.

When the Unloaded event is raised on an element, it's parent element or any element higher in the logical or visual tree may have already been unset. Unset means that an element's data bindings, resource references, and styles are no longer set to their normal or last known run-time value.

Other lifetime events

From the lifetime events perspective, there are four main types of WPF objects: elements in general, window elements, navigation hosts, and application objects. The Initialized, Loaded, and Unloaded lifetime events apply to all framework-level elements. Other lifetime events specifically apply to window elements, navigation hosts, or application objects. For information about those other lifetime events, see:

Application management overview for Application objects.
Overview of WPF windows for Window elements.
Navigation overview for Page, NavigationWindow, and Frame elements.

Share via