readme

packages/shared_preferences/shared_preferences/README.md

@@ -161,18 +161,22 @@ await prefsWithCache.clear();
 
 #### Migrating from SharedPreferences to SharedPreferencesAsync/WithCache
 
-Currently, migration from the older [SharedPreferences] API to the newer 
-[SharedPreferencesAsync] or [SharedPreferencesWithCache] will need to be done manually.
+Migrating to the newer `SharedPreferencesAsync` or `SharedPreferencesWithCache` API's is straightforward.
+All that is need is to import the migration utility, and provide it with the `SharedPreferences` instance 
+that was being used previously, as well as the options for the desired new API options.
 
-A simple form of this could be fetching all preferences with [SharedPreferences] and adding 
-them back using [SharedPreferencesAsync], then storing a preference indicating that the 
-migration has been done so that future runs don't repeat the migration.
+This can be run on every launch without data loss as long as the [migrationCompletedKey] is not altered or deleted.
 
-If a migration is not performed before moving to [SharedPreferencesAsync] or [SharedPreferencesWithCache],
-most (if not all) data will be lost. Android preferences are stored in a new system, and all platforms
-are likely to have some form of enforced prefix (see below) that would not transfer automatically.
-
-A tool to make this process easier can be tracked here: https://github.com/flutter/flutter/issues/150732
+<?code-excerpt "main.dart (migrate)"?>
+```dart
+import 'package:shared_preferences/util/legacy_to_async_migration_util.dart';
+// ···
+    const SharedPreferencesOptions sharedPreferencesOptions =
+        SharedPreferencesOptions();
+    final SharedPreferences prefs = await SharedPreferences.getInstance();
+    await migrateLegacySharedPreferencesToSharedPreferencesAsyncIfNecessary(
+        prefs, sharedPreferencesOptions, 'migrationCompleted');
+```
 
 #### Adding, Removing, or changing prefixes on SharedPreferences
 

packages/shared_preferences/shared_preferences/example/lib/main.dart

@@ -8,6 +8,10 @@ import 'dart:async';
 
 import 'package:flutter/material.dart';
 import 'package:shared_preferences/shared_preferences.dart';
+// #docregion migrate
+import 'package:shared_preferences/util/legacy_to_async_migration_util.dart';
+// #enddocregion migrate
+import 'package:shared_preferences_platform_interface/types.dart';
 
 void main() {
   runApp(const MyApp());
@@ -61,14 +65,25 @@ class SharedPreferencesDemoState extends State<SharedPreferencesDemo> {
     });
   }
 
+  Future<void> _migratePreferences() async {
+    // #docregion migrate
+    const SharedPreferencesOptions sharedPreferencesOptions =
+        SharedPreferencesOptions();
+    final SharedPreferences prefs = await SharedPreferences.getInstance();
+    await migrateLegacySharedPreferencesToSharedPreferencesAsyncIfNecessary(
+        prefs, sharedPreferencesOptions, 'migrationCompleted');
+    // #enddocregion migrate
+  }
+
   @override
   void initState() {
     super.initState();
-    _counter = _prefs.then((SharedPreferencesWithCache prefs) {
-      return prefs.getInt('counter') ?? 0;
+    _migratePreferences().then((_) {
+      _counter = _prefs.then((SharedPreferencesWithCache prefs) {
+        return prefs.getInt('counter') ?? 0;
+      });
+      _getExternalCounter();
     });
-
-    _getExternalCounter();
   }
 
   @override

packages/shared_preferences/shared_preferences/lib/util/legacy_to_async_migration_util.dart

@@ -10,12 +10,13 @@ import '../shared_preferences.dart';
 /// SharedPreferencesAsync.
 ///
 /// This method can be run multiple times without worry of overwriting transferred data,
-/// as long as the [migrationCompletedKey] is not altered manually.
+/// as long as migrationCompletedKey is the same each time, and the value stored
+/// under migrationCompletedKey in the target preferences system is not modified.
 ///
 /// [legacySharedPreferencesInstance] should be an instance of [SharedPreferences]
 /// that has been instantiated the same way it has been used throughout your app.
-/// If you have called [SharedPreferences.setPrefix] that must be done before using
-/// this tool.
+/// If you have called [SharedPreferences.setPrefix] that must be done before
+/// calling this method.
 ///
 /// [sharedPreferencesAsyncOptions] should be an instance of [SharedPreferencesOptions]
 /// that is set up the way you intend to use the new system going forward.