Missing a section on bringing VersionTracking migration code together?

munkii commented 1 month ago

Type of issue

Typo

Description

Firstly, thanks for all the effort in putting together the LegacyVersionTracking code. We need to migrate our SecureStorage, Preferences and VersionTracking from Xamarin Forms to MAUI.

I don't want to sound lazy or ungrateful but I feel there is a section in the docs that is missing.

If we take the Version Tracking migration as an example. In "Access legacy version tracking data" you explain how to get access to the VersionTracking that the XF version of the app would have written and how to expose it via a series of properties and methods. In the "Android" and "iOS" sections you show the platform specific classes needed to read the data exposed in "Access legacy version tracking data". In "Consume legacy version tracking data" you show how the data could be read, written to MAUI Preferences and then the old data removed.

What I feel like is missing is how that final peice would work in the practice.

The scenario is new MAUI version of the same app is opened for the first time on the device. What we would want is some code that would see it is an update not a new version then copy over the old data to the new localtion and that code never run again.

Could that be acheived with

if (VersionTracking.IsFirstLaunch == true && LegacyVersionTracking.IsFirstLaunchEver == false)

As the XF data has yet to be copied over VersionTracking.IsFirstLaunch would be True and with the XF data having yet to be removed/migrated the LegacyVersionTracking.IsFirstLaunchEver would still be false.

What do you think about having something like that as a conclusion and do you agree that would work?

Page URL

https://learn.microsoft.com/en-us/dotnet/maui/migration/version-tracking?view=net-maui-8.0

Content source URL

https://github.com/dotnet/docs-maui/blob/main/docs/migration/version-tracking.md

Document Version Independent Id

eab654d6-44ef-a076-40e1-2bb873940e89

Article author

@davidbritch

Metadata

ID: eab654d6-44ef-a076-40e1-2bb873940e89
Service: dotnet-mobile
Sub-service: dotnet-maui

munkii commented 2 weeks ago

@davidbritch would you mind giving me some feedback

Do you think my suggestion below is mad approach?

if (VersionTracking.IsFirstLaunch == true && LegacyVersionTracking.IsFirstLaunchEver == false)

As the XF data has yet to be copied over VersionTracking.IsFirstLaunch would be True and with the XF data having yet to be removed/migrated the LegacyVersionTracking.IsFirstLaunchEver would still be false.

Secondly do you think that would be a worthwhile addition to the docs?

davidbritch commented 2 weeks ago

Hi @munkii

I'm not sure that's wise (assuming you mean VersionTracking.IsFirstLaunchEver or VersionTracking.IsFirstLaunchForCurrentVersion).

Looking at the VersionTracking source code it looks IsFirstLaunchEver is set to true provided that (1) there's a {your-app-package-id}.microsoft.maui.essentials.versiontracking container, and (2) the container contains a key called VersionTracking.Versions. Once that container exists it'll contain all kinds of version tracking data that might interfere with the data you're trying to migrate.

It would be safer to do something like (pseudo-code):

if (LegacyVersionTracking data is present)
{
    Read data using `LegacyVersionTracking`
    Write data to preferences with `WriteHistory`
    Remove legacy version tracking data
}

How to check if LVT data is present? It'd be something like:

```csharp
if (LegacyPreferences.ContainsKey(LegacyVersionTracking.VersionsKey, LegacyVersionTracking.SharedName))
{

}

Hope this helps.

dotnet / docs-maui