Merge branch 'main' into dabritch-net8

Author: davidbritch

docs/TOC.yml

@@ -89,6 +89,8 @@
               href: migration/app-properties.md
             - name: Migrate secure storage data
               href: migration/secure-storage.md
+            - name: Migrate version tracking data
+              href: migration/version-tracking.md
     - name: Tutorials
       items:
         - name: Create a .NET MAUI app

docs/migration/app-properties.md

@@ -21,10 +21,12 @@ The following code shows the `LegacyApplication` class, which provides access to
 > To use this code, add it to a class named `LegacyApplication` in your .NET MAUI app project.
 
 ```csharp
+namespace MigrationHelpers;
+
 public class LegacyApplication
 {
-    readonly PropertiesDeserializer _deserializer;
-    Task<IDictionary<string, object>>? _propertiesTask;
+    readonly PropertiesDeserializer deserializer;
+    Task<IDictionary<string, object>>? propertiesTask;
 
     static LegacyApplication? current;
     public static LegacyApplication? Current
@@ -38,21 +40,21 @@ public class LegacyApplication
 
     public LegacyApplication()
     {
-        _deserializer = new PropertiesDeserializer();
+        deserializer = new PropertiesDeserializer();
     }
 
     public IDictionary<string, object> Properties
     {
         get
         {
-            _propertiesTask ??= GetPropertiesAsync();
-            return _propertiesTask.Result;
+            propertiesTask ??= GetPropertiesAsync();
+            return propertiesTask.Result;
         }
     }
 
     async Task<IDictionary<string, object>> GetPropertiesAsync()
     {
-        IDictionary<string, object> properties = await _deserializer.DeserializePropertiesAsync().ConfigureAwait(false);
+        IDictionary<string, object> properties = await deserializer.DeserializePropertiesAsync().ConfigureAwait(false);
         properties ??= new Dictionary<string, object>(4);
         return properties;
     }

docs/migration/includes/compile-troubleshoot.md

@@ -1,6 +1,6 @@
 ---
 ms.topic: include
-ms.date: 10/02/2023
+ms.date: 10/06/2023
 ---
 
 ## Compile and troubleshoot
@@ -29,4 +29,5 @@ The following table provides guidance for overcoming common build or runtime iss
 | Custom renderer doesn't work. | Renderer code needs updating to work in .NET MAUI. For more information, see [Use custom renderers in .NET MAUI](../custom-renderers.md). |
 | Effect doesn't work. | Effect code needs updating to work in .NET MAUI. For more information, see [Use effects in .NET MAUI](../effects.md). |
 | Can't access previously created app properties data. | Migrate the app properties data to .NET MAUI preferences. For more information, see [Migrate data from the Xamarin.Forms app properties dictionary to .NET MAUI preferences](../app-properties.md). |
-| Can't access previously created secure storage. | There are implementation differences between the `SecureStorage` class in Xamarin.Essentials and .NET MAUI. For more information, see [Migrate from Xamarin.Essentials secure storage to .NET MAUI secure storage](../secure-storage.md). |
+| Can't access previously created secure storage data. | Migrate the secure storage data to .NET MAUI. For more information, see [Migrate from Xamarin.Essentials secure storage to .NET MAUI secure storage](../secure-storage.md). |
+| Can't access previously created version tracking data. | Migrate the version tracking data to .NET MAUI. For more information, see [Migrate version tracking data from a Xamarin.Forms app to a .NET MAUI app](../version-tracking.md). |

docs/migration/secure-storage.md

@@ -10,7 +10,7 @@ Xamarin.Essentials and .NET Multi-platform App UI (.NET MAUI) both have a `Secur
 
 | Platform | Xamarin.Essentials | .NET MAUI |
 | - | ------------------ | --------- |
-| Android | The Android KeyStore is used to store the cipher key used to encrypt a value before it's saved into a shared preferences object with a filename of {your-app-package-id}.xamarinessentials. | Data is encrypted with the `EncryptedSharedPreferences` class, which wraps the `SharedPreferences` class, and automatically encrypts keys and values. The filename used is {your-app-package-id}.microsoft.maui.essentials.preferences. |
+| Android | The Android KeyStore is used to store the cipher key used to encrypt a value before it's saved into a shared preferences object with a name of {your-app-package-id}.xamarinessentials. | Data is encrypted with the `EncryptedSharedPreferences` class, which wraps the `SharedPreferences` class, and automatically encrypts keys and values. The name used is {your-app-package-id}.microsoft.maui.essentials.preferences. |
 | iOS | KeyChain is used to store values securely. The `SecRecord` used to store values has a `Service` value set to {your-app-package-id}.xamarinessentials. | KeyChain is used to store values securely. The `SecRecord` used to store values has a `Service` value set to {your-app-package-id}.microsoft.maui.essentials.preferences. |
 <!-- | Windows | The `DataProtectionProvider` class is used to encrypt values securely. Encrypted values are stored in `ApplicationData.Current.LocalSettings`, inside a container with a name of {your-app-package-id}.xamarinessentials. | The `DataProtectionProvider` class is used to encrypt values securely. Encrypted values are stored in `ApplicationData.Current.LocalSettings`, inside a container with a name of {your-app-package-id}.microsoft.maui.essentials.preferences. | -->
 
@@ -91,7 +91,7 @@ public class LegacySecureStorage
 
 ### Android
 
-On Android, the `LegacySecureStorage` class uses the `AndroidKeyStore` class to store the cipher key used to encrypt a value before it's saved into a shared preferences object with a filename of {your-app-package-id}.xamarinessentials. The following code shows the `AndroidKeyStore` class:
+On Android, the `LegacySecureStorage` class uses the `AndroidKeyStore` class to store the cipher key used to encrypt a value before it's saved into a shared preferences object with a name of {your-app-package-id}.xamarinessentials. The following code shows the `AndroidKeyStore` class:
 
 > [!NOTE]
 > To use this code, add it to a class named `AndroidKeyStore` in the *Platforms\Android* folder of your .NET MAUI app project.
@@ -347,7 +347,7 @@ class AndroidKeyStore
 }
 ```
 
-The [Android KeyStore](https://developer.android.com/training/articles/keystore.html) is used to store the cipher key used to encrypt the value before it is saved into a [Shared Preferences](https://developer.android.com/training/data-storage/shared-preferences.html)file with a filename of *{your-app-package-id}.xamarinessentials*. The key (not a cryptographic key, the *key* to the *value*) used in the shared preferences file is a *MD5 Hash* of the key passed into the `SecureStorage` APIs.
+The [Android KeyStore](https://developer.android.com/training/articles/keystore.html) is used to store the cipher key used to encrypt the value before it is saved into a [Shared Preferences](https://developer.android.com/training/data-storage/shared-preferences.html)file with a name of *{your-app-package-id}.xamarinessentials*. The key (not a cryptographic key, the *key* to the *value*) used in the shared preferences file is a *MD5 Hash* of the key passed into the `SecureStorage` APIs.
 
 On API 23+, an **AES** key is obtained from the Android KeyStore and used with an **AES/GCM/NoPadding** cipher to encrypt the value before it is stored in the shared preferences file. On API 22 and lower, the Android KeyStore only supports storing **RSA** keys, which is used with an **RSA/ECB/PKCS1Padding** cipher to encrypt an **AES** key (randomly generated at runtime) and stored in the shared preferences file under the key _SecureStorageKey_, if one has not already been generated.