Xamarin.Forms App Lifecycle Tutorial

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.

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

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

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

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

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

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

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

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

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

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

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

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

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

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