Finalize LegacyVersionTracking

Author: jfversluis

samples/Plugin.Maui.FormsMigration.Sample/MainPage.xaml.cs

@@ -10,9 +10,11 @@ public MainPage()
 	// SecureStorage Example
 	async void SecureStorage_Clicked(object sender, EventArgs e)
 	{
+		// More information: https://learn.microsoft.com/dotnet/maui/migration/secure-storage
+		
 		// Xamarin.Essentials SecureStorage stores its data in $(AppInfo.PackageName).xamarinessentials
 		// MAUI SecureStorage stores its data in $(AppInfo.PackageName).microsoft.maui.essentials.preferences
-		// MAUI also uses different encryption for SecureStorage than used in Xamarin.Essentials (I think)
+		// MAUI also uses different encryption for SecureStorage than used in Xamarin.Essentials.
 
 		// $(AppInfo.PackageName) is referring to the Microsoft.Maui.ApplicationModel.AppInfo APIs and
 		// will be replaced with your actual application ID. These should be the same for both your old app and new app.
@@ -28,7 +30,11 @@ async void SecureStorage_Clicked(object sender, EventArgs e)
 	// VersionTracking Example
 	void VersionTracking_Clicked(object sender, EventArgs e)
 	{
-		// TBD
+		// More information: https://learn.microsoft.com/dotnet/maui/migration/version-tracking
+
+		// Retrieve values from your legacy Xamarin application through the LegacyVersionTracking class.
+
+		// Read legacy version/build number information
 		labelIsFirst.Text = LegacyVersionTracking.IsFirstLaunchEver.ToString();
 		labelCurrentVersionIsFirst.Text = LegacyVersionTracking.IsFirstLaunchForCurrentVersion.ToString();
 		labelCurrentBuildIsFirst.Text = LegacyVersionTracking.IsFirstLaunchForCurrentBuild.ToString();
@@ -43,20 +49,22 @@ void VersionTracking_Clicked(object sender, EventArgs e)
 		labelPreviousVersion.Text = LegacyVersionTracking.PreviousVersion?.ToString() ?? "none";
 		labelPreviousBuild.Text = LegacyVersionTracking.PreviousBuild?.ToString() ?? "none";
 
-		List<string> vhistory = new() { "1.0", "2.0", "3.0", "4.0", "5.0" };
-		List<string> bhistory = new() { "1", "2", "3", "4", "5" };
+		// Transfer the full legacy Xamarin app version tracking information (version & build numbers)
+		// to the .NET MAUI Version Tracking data store. Before doing so the *new* .NET MAUI Version Tracking
+		// store will be cleared.
+		LegacyVersionTracking.TransferHistory(true, true, true);
 	}
 
 	// Properties Example
 	void AppProperties_Clicked(object sender, EventArgs e)
 	{
+		// More information: https://learn.microsoft.com/dotnet/maui/migration/app-properties
+
 		// Retrieve values from your legacy Xamarin application through the LegacyApplication class.
 
 		// The code below assumes that there is a property value saved with the key "id". Replace this key
 		// with any value(s) you have stored in your legacy Xamarin app to get them out.
 
-		// For more information, see: https://learn.microsoft.com/dotnet/maui/migration/app-properties
-
 		int id;
 		if (LegacyApplication.Current.Properties.ContainsKey("id"))
 		{

src/Plugin.Maui.FormsMigration/VersionTracking/LegacyPreferences.shared.cs

@@ -4,9 +4,10 @@ namespace Plugin.Maui.FormsMigration;
 
 static partial class LegacyPreferences
 {
-	internal static string GetPrivatePreferencesSharedName(string feature) => $"{AppInfo.PackageName}.xamarinessentials.{feature}";
+	internal static string GetPrivatePreferencesSharedName(string feature) =>
+		$"{AppInfo.PackageName}.xamarinessentials.{feature}";
 
 	internal static bool ContainsKey(string key, string sharedName) => PlatformContainsKey(key, sharedName);
 	internal static void Remove(string key, string sharedName) => PlatformRemove(key, sharedName);
-	internal static string Get(string key, string defaultValue, string sharedName) => PlatformGet<string>(key, defaultValue, sharedName);
+	internal static string Get(string key, string? defaultValue, string sharedName) => PlatformGet<string>(key, defaultValue, sharedName);
 }

src/Plugin.Maui.FormsMigration/VersionTracking/LegacyVersionTracking.shared.cs

@@ -1,9 +1,17 @@
 using Microsoft.Maui.ApplicationModel;
+using Microsoft.Maui.Storage;
 
 namespace Plugin.Maui.FormsMigration;
 
+/// <summary>
+/// The LegacyVersionTracking API can be used to access the legacy Xamarin application version tracking information in your .NET MAUI app.
+/// </summary>
+/// <remarks>Important: make sure that your .NET MAUI app version is higher than the legacy application version number. Not doing so might have unexpected results.</remarks>
 public static class LegacyVersionTracking
 {
+	static string PrivateVersionTrackingSharedNameMaui =>
+		$"{AppInfo.Current.PackageName}.microsoft.maui.essentials.versiontracking";
+
 	const string versionsKey = "VersionTracking.Versions";
 	const string buildsKey = "VersionTracking.Builds";
 
@@ -20,6 +28,31 @@ static LegacyVersionTracking()
 		InitVersionTracking();
 	}
 
+	/// <summary>
+	/// Transfers the version and/or build number information from the legacy Xamarin app to the .NET MAUI Version Tracking data store.
+	/// </summary>
+	/// <param name="includeVersionInfo">Determines whether or not version number information should be included in the transfer.</param>
+	/// <param name="includeBuildInfo">Determines whether or not build number information should be included in the transfer.</param>
+	/// <param name="clearMauiVersionHistory">Determines whether or not to clear the current .NET MAUI app version history before transferring the legacy Xamarin app history.</param>
+	/// <remarks>When not setting <paramref name="clearMauiVersionHistory"/> to <see langword="true"/>, newer version/build numbers might appear before the legacy version/build number history.</remarks>
+	public static void TransferHistory(bool includeVersionInfo, bool includeBuildInfo, bool clearMauiVersionHistory)
+	{
+		if (clearMauiVersionHistory)
+		{
+			Preferences.Default.Clear(PrivateVersionTrackingSharedNameMaui);
+		}
+
+		if (includeVersionInfo)
+		{
+			WriteVersionTrackingHistory(VersionsKey, LegacyVersionTracking.VersionHistory);
+		}
+
+		if (includeBuildInfo)
+		{
+			WriteVersionTrackingHistory(BuildsKey, LegacyVersionTracking.BuildHistory);
+		}
+	}
+
 	/// <summary>
 	/// Initialize VersionTracking module, load data and track current version.
 	/// </summary>
@@ -96,22 +129,22 @@ internal static void InitVersionTracking()
 	/// <summary>
 	/// Gets the version number for the previously run version of the legacy Xamarin app.
 	/// </summary>
-	public static string PreviousVersion => GetPrevious(versionsKey);
+	public static string? PreviousVersion => GetPrevious(versionsKey);
 
 	/// <summary>
 	/// Gets the build number for the previously run version of the legacy Xamarin app.
 	/// </summary>
-	public static string PreviousBuild => GetPrevious(buildsKey);
+	public static string? PreviousBuild => GetPrevious(buildsKey);
 
 	/// <summary>
 	/// Gets the version number of the first version of the app legacy Xamarin that was installed on this device.
 	/// </summary>
-	public static string FirstInstalledVersion => versionTrail[versionsKey].FirstOrDefault();
+	public static string? FirstInstalledVersion => versionTrail[versionsKey].FirstOrDefault();
 
 	/// <summary>
 	/// Gets the build number of first version of the legacy Xamarin app that was installed on this device.
 	/// </summary>
-	public static string FirstInstalledBuild => versionTrail[buildsKey].FirstOrDefault();
+	public static string? FirstInstalledBuild => versionTrail[buildsKey].FirstOrDefault();
 
 	/// <summary>
 	/// Gets the collection of version numbers of the legacy Xamarin app that ran on this device.
@@ -143,13 +176,19 @@ static string[] ReadHistory(string key)
 		=> LegacyPreferences.Get(key, null, sharedName)?.Split(new[] { '|' },
 			StringSplitOptions.RemoveEmptyEntries) ?? Array.Empty<string>();
 
-	static string GetPrevious(string key)
+	static string? GetPrevious(string key)
 	{
 		var trail = versionTrail[key];
 		return (trail.Count >= 2) ? trail[trail.Count - 2] : null;
 	}
 
-	static string LastInstalledVersion => versionTrail[versionsKey].LastOrDefault();
+	static string? LastInstalledVersion => versionTrail[versionsKey].LastOrDefault();
+
+	static string? LastInstalledBuild => versionTrail[buildsKey].LastOrDefault();
 
-	static string LastInstalledBuild => versionTrail[buildsKey].LastOrDefault();
+	static void WriteVersionTrackingHistory(string key, IEnumerable<string> history)
+    {        
+        Preferences.Default.Set(key, string.Join("|", history),
+			PrivateVersionTrackingSharedNameMaui);
+    }
 }