Xamarin.Forms App Lifecycle Tutorial

Article
Developer (Beginner)
8 minutes to complete

Before attempting this tutorial, you should have successfully completed the:

Build your first Xamarin.Forms app quickstart.
StackLayout tutorial.
Entry tutorial.

In this tutorial, you learn how to:

Respond to an application starting, sleeping, or resuming.
Persist data across lifecycle state changes.

You will use Visual Studio 2019, or Visual Studio for Mac, to create a simple application that demonstrates how to persist data across lifecycle state changes. The following screenshots show the final application:

Respond to lifecycle state changes

7 minutes remaining

Visual Studio
Visual Studio for Mac

To complete this tutorial you should have Visual Studio 2019 (latest release), with the Mobile development with .NET workload installed. In addition, you will require a paired Mac to build the tutorial application on iOS. For information about installing the Xamarin platform, see Installing Xamarin. For information about connecting Visual Studio 2019 to a Mac build host, see Pair to Mac for Xamarin.iOS development.

Launch Visual Studio, and create a new blank Xamarin.Forms app named AppLifecycleTutorial.

Important

The C# and XAML snippets in this tutorial requires that the solution is named AppLifecycleTutorial. Using a different name will result in build errors when you copy code from this tutorial into the solution.

For more information about the .NET Standard library that gets created, see Anatomy of a Xamarin.Forms application in the Xamarin.Forms Quickstart Deep Dive.
In Solution Explorer, in the AppLifecycleTutorial project, expand App.xaml and double-click App.xaml.cs to open it. Then, in App.xaml.cs, update the OnStart, OnSleep, and OnResume overrides as follows:
```
protected override void OnStart()
{
    Console.WriteLine("OnStart");
}

protected override void OnSleep()
{
    Console.WriteLine("OnSleep");
}

protected override void OnResume()
{
    Console.WriteLine("OnResume");
}
```
This code updates the application lifecycle method overrides, with Console.WriteLine statements that indicate when each method has been invoked:
- The OnStart method is invoked when the application starts.
- The OnSleep method is invoked when the application goes to the background.
- The OnResume method is invoked when the application resumes from the background.
Note

There is no method for application termination. Under normal circumstances, application termination will occur from the OnSleep method.
In the Visual Studio toolbar, press the Start button (the triangular button that resembles a Play button) to launch the application inside your chosen remote iOS simulator or Android emulator. When the application starts, the OnStart method is invoked, and OnStart is output to the Visual Studio Output window:
```
[Mono] Found as 'java_interop_jnienv_get_object_array_element'.
OnStart
[OpenGLRenderer] HWUI GL Pipeline
```
When the application is backgrounded (by tapping the Home button on iOS or Android), the OnSleep method is invoked:
```
[EGL_emulation] eglMakeCurrent: 0x83ee2920: ver 3 0 (tinfo 0x8357eff0)
OnSleep
[Mono] Image addref System.Runtime.Serialization[0x83ee19c0] -> System.Runtime.Serialization.dll[0x83f57b00]: 2
```
Then, when the application resumes from the background (tap the application icon on iOS, tap the Overview button on Android and select the AppLifecycleTutorial application), the OnResume method is invoked:
```
Thread finished: <Thread Pool> #5
OnResume
[EGL_emulation] eglMakeCurrent: 0x83ee2920: ver 3 0 (tinfo 0x8357eff0)
```
Note

These code blocks show example output when running the application on Android.

In Visual Studio, stop the application.

For more information about the Xamarin.Forms app lifecycle, see Xamarin.Forms App Lifecycle.

To complete this tutorial you should have Visual Studio for Mac (latest release), with iOS and Android platform support installed. In addition, you will also require Xcode (latest release). For more information about installing the Xamarin platform, see Installing Xamarin.

Launch Visual Studio for Mac, and create a new blank Xamarin.Forms app named AppLifecycleTutorial.

Important

The C# and XAML snippets in this tutorial requires that the solution is named AppLifecycleTutorial. Using a different name will result in build errors when you copy code from this tutorial into the solution.

For more information about the .NET Standard library that gets created, see Anatomy of a Xamarin.Forms application in the Xamarin.Forms Quickstart Deep Dive.
In Solution Pad, in the AppLifecycleTutorial project, expand App.xaml and double-click App.xaml.cs to open it. Then, in App.xaml.cs, update the OnStart, OnSleep, and OnResume overrides as follows:
```
protected override void OnStart()
{
    Console.WriteLine("OnStart");
}

protected override void OnSleep()
{
    Console.WriteLine("OnSleep");
}

protected override void OnResume()
{
    Console.WriteLine("OnResume");
}
```
This code updates the application lifecycle method overrides, with Console.WriteLine statements that indicate when each method has been invoked:
- The OnStart method is invoked when the application starts.
- The OnSleep method is invoked when the application goes to the background.
- The OnResume method is invoked when the application resumes from the background.
Note

There is no method for application termination. Under normal circumstances, application termination will occur from the OnSleep method.

In the Visual Studio for Mac toolbar, press the Start button (the triangular button that resembles a Play button) to launch the application inside your chosen iOS simulator or Android emulator. When the application starts, the OnStart method is invoked, and OnStart is output to the Visual Studio for Mac Application Output window:

2019-02-11 12:05:23.164761+0000 AppLifecycleTutorial.iOS[4089:361037] SecTaskLoadEntitlements failed error=22 cs_flags=200, pid=4089
2019-02-11 12:05:23.165297+0000 AppLifecycleTutorial.iOS[4089:361037] SecTaskCopyDebugDescription: AppLifecycleTuto[4089]/0#-1 LF=0
2019-02-11 12:05:23.685430+0000 AppLifecycleTutorial.iOS[4089:361037] OnStart

When the application is backgrounded (by tapping the Home button on iOS or Android), the OnSleep method is invoked:

2019-02-11 12:06:12.394301+0000 AppLifecycleTutorial.iOS[4089:361037] OnSleep
Thread started: <Thread Pool> #3
Thread started: <Thread Pool> #4
Thread started: <Thread Pool> #5
Thread started: <Thread Pool> #6
2019-02-11 12:06:13.056968+0000 AppLifecycleTutorial.iOS[4089:361037] SecTaskLoadEntitlements failed error=22 cs_flags=200, pid=4089
2019-02-11 12:06:13.057264+0000 AppLifecycleTutorial.iOS[4089:361037] SecTaskCopyDebugDescription: AppLifecycleTuto[4089]/0#-1 LF=0

Then, when the application resumes from the background (tap the application icon on iOS, tap the Overview button on Android and select the AppLifecycleTutorial application), the OnResume method is invoked:

2019-02-11 12:07:10.321905+0000 AppLifecycleTutorial.iOS[4130:365695] SecTaskLoadEntitlements failed error=22 cs_flags=200, pid=4130
2019-02-11 12:07:10.322557+0000 AppLifecycleTutorial.iOS[4130:365695] SecTaskCopyDebugDescription: AppLifecycleTuto[4130]/0#-1 LF=0
2019-02-11 12:07:17.110938+0000 AppLifecycleTutorial.iOS[4130:365695] OnResume

Note

These code blocks show example output when running the application on iOS.

In Visual Studio for Mac, stop the application.

For more information about the Xamarin.Forms app lifecycle, see Xamarin.Forms App Lifecycle.

Persist data across lifecycle state changes

4 minutes remaining

The Application subclass has a static Properties dictionary that can be used to store data across lifecycle state changes. This dictionary uses a string key and stores an object value. The dictionary is saved to the device automatically, and is repopulated when the application is restarted.

Important

The Properties dictionary can only serialize primitive types for storage.

In this exercise, you'll modify the application to persist the text from an Entry upon backgrounding, and restore the text to the Entry when the application is restarted.

Visual Studio
Visual Studio for Mac

In Solution Explorer, in the AppLifecycleTutorial project, expand App.xaml and double-click App.xaml.cs to open it. Then, in App.xaml.cs, remove all of the template code and replace it with the following code:
```
using System;
using Xamarin.Forms;

namespace AppLifecycleTutorial
{
    public partial class App : Application
    {
        const string displayText = "displayText";

        public string DisplayText { get; set; }

        public App()
        {
            InitializeComponent();

            MainPage = new MainPage();
        }

        protected override void OnStart()
        {
            Console.WriteLine("OnStart");

            if (Properties.ContainsKey(displayText))
            {
                DisplayText = (string)Properties[displayText];
            }
        }

        protected override void OnSleep()
        {
            Console.WriteLine("OnSleep");
            Properties[displayText] = DisplayText;
        }

        protected override void OnResume()
        {
            Console.WriteLine("OnResume");
        }
    }
}
```
This code defines a DisplayText property, and a displayText constant. When the application is backgrounded, or terminated, the OnSleep method override adds the DisplayText property value to the Properties dictionary, against a key of displayText. Then when the application starts, provided that the Properties dictionary contains the displayText key, the value for the key is restored to the DisplayText property.

Important

Always check the Properties dictionary for the presence of a key before accessing it, to prevent unexpected errors.

It's not necessary to restore data from the Properties dictionary in the OnResume method overload. This is because when an application is backgrounded, it and its state is still in memory.
In Solution Explorer, in the AppLifecycleTutorial project, double-click MainPage.xaml to open it. Then, in MainPage.xaml, remove all of the template code and replace it with the following code:
```
<?xml version="1.0" encoding="utf-8"?>
<ContentPage xmlns="http://xamarin.com/schemas/2014/forms"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             x:Class="AppLifecycleTutorial.MainPage">
    <StackLayout Margin="20,35,20,20">
        <Entry x:Name="entry"
               Placeholder="Enter text here"
               Completed="OnEntryCompleted" />
    </StackLayout>
</ContentPage>
```
This code declaratively defines the user interface for the page, which consists of an Entry in a StackLayout. The Entry.Placeholder property specifies the placeholder text that's shown when the Entry is first displayed, and an event handler named OnEntryCompleted is registered with the Completed event. In addition, the Entry has a name specified with the x:Name attribute. This enables the code-behind file to access the Entry object using the name assigned to it.
In Solution Explorer, in the AppLifecycleTutorial project, expand MainPage.xaml and double-click MainPage.xaml.cs to open it. Then, in MainPage.xaml.cs, add an override for the OnAppearing method, and the OnEntryCompleted event handler to the class:
```
protected override void OnAppearing()
{
    base.OnAppearing();

    entry.Text = (Application.Current as App).DisplayText;
}

void OnEntryCompleted(object sender, EventArgs e)
{
    (Application.Current as App).DisplayText = entry.Text;
}
```
The OnAppearing method retrieves the value of the App.DisplayText property and sets it as the Text property value of the Entry.

Note

The OnAppearing method override is executed after the ContentPage is laid out, but just before it becomes visible. Therefore, this is a good place to set the content of Xamarin.Forms views.

When text is finalized in the Entry, with the return key, the OnEntryCompleted method executes and the Entry text is stored in the App.DisplayText property.
In the Visual Studio toolbar, press the Start button (the triangular button that resembles a Play button) to launch the application inside your chosen remote iOS simulator or Android emulator.

Enter some text into the Entry and hit the return key. Then, background the application by tapping the Home button to invoke the OnSleep method.

In Visual Studio, stop the application and relaunch it again, and the text that was previously entered into the Entry will be restored:

In Visual Studio, stop the application.

For more information about persisting data to the properties dictionary, see Properties Dictionary in the Xamarin.Forms App Class guide.

In Solution Pad, in the AppLifecycleTutorial project, expand App.xaml and double-click App.xaml.cs to open it. Then, in App.xaml.cs, remove all of the template code and replace it with the following code:
```
using System;
using Xamarin.Forms;

namespace AppLifecycleTutorial
{
    public partial class App : Application
    {
        const string displayText = "displayText";

        public string DisplayText { get; set; }

        public App()
        {
            InitializeComponent();

            MainPage = new MainPage();
        }

        protected override void OnStart()
        {
            Console.WriteLine("OnStart");

            if (Properties.ContainsKey(displayText))
            {
                DisplayText = (string)Properties[displayText];
            }
        }

        protected override void OnSleep()
        {
            Console.WriteLine("OnSleep");
            Properties[displayText] = DisplayText;
        }

        protected override void OnResume()
        {
            Console.WriteLine("OnResume");
        }
    }
}
```
This code defines a DisplayText property, and a displayText constant. When the application is backgrounded, or terminated, the OnSleep method override adds the DisplayText property value to the Properties dictionary, against a key of displayText. Then when the application starts, provided that the Properties dictionary contains the displayText key, the value for the key is restored to the DisplayText property.

Important

Always check the Properties dictionary for the presence of a key before accessing it, to prevent unexpected errors.

It's not necessary to restore data from the Properties dictionary in the OnResume method overload. This is because when an application is backgrounded, it and its state is still in memory.
In Solution Pad, in the AppLifecycleTutorial project, double-click MainPage.xaml to open it. Then, in MainPage.xaml, remove all of the template code and replace it with the following code:
```
<?xml version="1.0" encoding="utf-8"?>
<ContentPage xmlns="http://xamarin.com/schemas/2014/forms"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             x:Class="AppLifecycleTutorial.MainPage">
    <StackLayout Margin="20,35,20,20">
        <Entry x:Name="entry"
               Placeholder="Enter text here"
               Completed="OnEntryCompleted" />
    </StackLayout>
</ContentPage>
```
This code declaratively defines the user interface for the page, which consists of an Entry in a StackLayout. The Entry.Placeholder property specifies the placeholder text that's shown when the Entry is first displayed, and an event handler named OnEntryCompleted is registered with the Completed event. In addition, the Entry has a name specified with the x:Name attribute. This enables the code-behind file to access the Entry object using the name assigned to it.
In Solution Pad, in the AppLifecycleTutorial project, expand MainPage.xaml and double-click MainPage.xaml.cs to open it. Then, in MainPage.xaml.cs, add an override for the OnAppearing method, and the OnEntryCompleted event handler to the class:
```
protected override void OnAppearing()
{
    base.OnAppearing();

    entry.Text = (Application.Current as App).DisplayText;
}

void OnEntryCompleted(object sender, EventArgs e)
{
    (Application.Current as App).DisplayText = entry.Text;
}
```
The OnAppearing method retrieves the value of the App.DisplayText property and sets it as the Text property value of the Entry.

Note

The OnAppearing method override is executed after the ContentPage is laid out, but just before it becomes visible. Therefore, this is a good place to set the content of Xamarin.Forms views.

When text is finalized in the Entry, with the return key, the OnEntryCompleted method executes and the Entry text is stored in the App.DisplayText property.
In the Visual Studio for Mac toolbar, press the Start button (the triangular button that resembles a Play button) to launch the application inside your chosen iOS simulator or Android emulator.

Enter some text into the Entry and hit the return key. Then, background the application by tapping the Home button to invoke the OnSleep method.

In Visual Studio for Mac, stop the application and relaunch it again, and the text that was previously entered into the Entry will be restored:

In Visual Studio for Mac, stop the application.

For more information about persisting data to the properties dictionary, see Properties Dictionary in the Xamarin.Forms App Class guide.

Xamarin.Forms App Lifecycle Tutorial

Respond to lifecycle state changes

Persist data across lifecycle state changes

Congratulations!

Next steps

Xamarin.Forms App Lifecycle Tutorial

Respond to lifecycle state changes

Persist data across lifecycle state changes

Congratulations!

Next steps

Related links