PR updates

Author: shweaver-MSFT

Microsoft.Toolkit.Uwp/Helpers/ObjectStorage/ApplicationDataStorageHelper.CacheFolder.cs

@@ -16,20 +16,10 @@ namespace Microsoft.Toolkit.Uwp.Helpers
     public partial class ApplicationDataStorageHelper
     {
         /// <summary>
-        ///  Gets the storage folder.
+        ///  Gets the local cache folder.
         /// </summary>
         public StorageFolder CacheFolder => AppData.LocalCacheFolder;
 
-        /// <summary>
-        /// Determines if a directory item already exists in the LocalCacheFolder.
-        /// </summary>
-        /// <param name="itemName">Key of the file.</param>
-        /// <returns>True if an item exists.</returns>
-        public Task<bool> CacheItemExistsAsync(string itemName)
-        {
-            return ItemExistsAsync(CacheFolder, itemName);
-        }
-
         /// <summary>
         /// Retrieves an object from a file in the LocalCacheFolder.
         /// </summary>
@@ -47,7 +37,7 @@ public Task<T> ReadCacheFileAsync<T>(string filePath, T @default = default)
         /// </summary>
         /// <param name="folderPath">The path to the target folder.</param>
         /// <returns>A list of file types and names in the target folder.</returns>
-        public Task<IList<Tuple<DirectoryItemType, string>>> ReadCacheFolderAsync(string folderPath)
+        public Task<IEnumerable<(DirectoryItemType, string)>> ReadCacheFolderAsync(string folderPath)
         {
             return ReadFolderAsync(CacheFolder, folderPath);
         }

Microsoft.Toolkit.Uwp/Helpers/ObjectStorage/ApplicationDataStorageHelper.cs

@@ -15,7 +15,7 @@ namespace Microsoft.Toolkit.Uwp.Helpers
     /// <summary>
     /// Storage helper for files and folders living in Windows.Storage.ApplicationData storage endpoints.
     /// </summary>
-    public partial class ApplicationDataStorageHelper : IFileStorageHelper, ISettingsStorageHelper
+    public partial class ApplicationDataStorageHelper : IFileStorageHelper, ISettingsStorageHelper<string>
     {
         /// <summary>
         /// Get a new instance using ApplicationData.Current and the provided serializer.
@@ -53,9 +53,12 @@ public static async Task<ApplicationDataStorageHelper> GetForUserAsync(User user
         /// <summary>
         /// Gets the storage host.
         /// </summary>
-        protected ApplicationData AppData { get; private set; }
+        protected ApplicationData AppData { get; }
 
-        private readonly Toolkit.Helpers.IObjectSerializer _serializer;
+        /// <summary>
+        /// Gets the serializer for converting stored values.
+        /// </summary>
+        protected Toolkit.Helpers.IObjectSerializer Serializer { get; }
 
         /// <summary>
         /// Initializes a new instance of the <see cref="ApplicationDataStorageHelper"/> class.
@@ -65,16 +68,54 @@ public static async Task<ApplicationDataStorageHelper> GetForUserAsync(User user
         public ApplicationDataStorageHelper(ApplicationData appData, Toolkit.Helpers.IObjectSerializer objectSerializer = null)
         {
             AppData = appData ?? throw new ArgumentNullException(nameof(appData));
-            _serializer = objectSerializer ?? new Toolkit.Helpers.SystemSerializer();
+            Serializer = objectSerializer ?? new Toolkit.Helpers.SystemSerializer();
         }
 
-        /// <inheritdoc />
+        /// <summary>
+        /// Determines whether a setting already exists.
+        /// </summary>
+        /// <param name="key">Key of the setting (that contains object).</param>
+        /// <returns>True if a value exists.</returns>
         public bool KeyExists(string key)
         {
             return Settings.Values.ContainsKey(key);
         }
 
         /// <inheritdoc />
+        public T Read<T>(string key, T @default = default)
+        {
+            if (!Settings.Values.TryGetValue(key, out var valueObj) || valueObj == null)
+            {
+                return @default;
+            }
+
+            return Serializer.Deserialize<T>(valueObj as string);
+        }
+
+        /// <inheritdoc />
+        public void Save<T>(string key, T value)
+        {
+            Settings.Values[key] = Serializer.Serialize(value);
+        }
+
+        /// <inheritdoc />
+        public void Delete(string key)
+        {
+            Settings.Values.Remove(key);
+        }
+
+        /// <inheritdoc />
+        public void Clear()
+        {
+            Settings.Values.Clear();
+        }
+
+        /// <summary>
+        /// Determines whether a setting already exists in composite.
+        /// </summary>
+        /// <param name="compositeKey">Key of the composite (that contains settings).</param>
+        /// <param name="key">Key of the setting (that contains object).</param>
+        /// <returns>True if a value exists.</returns>
         public bool KeyExists(string compositeKey, string key)
         {
             if (KeyExists(compositeKey))
@@ -89,18 +130,14 @@ public bool KeyExists(string compositeKey, string key)
             return false;
         }
 
-        /// <inheritdoc />
-        public T Read<T>(string key, T @default = default)
-        {
-            if (!Settings.Values.TryGetValue(key, out var value) || value == null)
-            {
-                return @default;
-            }
-
-            return _serializer.Deserialize<T>(value);
-        }
-
-        /// <inheritdoc />
+        /// <summary>
+        /// Retrieves a single item by its key in composite.
+        /// </summary>
+        /// <typeparam name="T">Type of object retrieved.</typeparam>
+        /// <param name="compositeKey">Key of the composite (that contains settings).</param>
+        /// <param name="key">Key of the object.</param>
+        /// <param name="default">Default value of the object.</param>
+        /// <returns>The T object.</returns>
         public T Read<T>(string compositeKey, string key, T @default = default)
         {
             ApplicationDataCompositeValue composite = (ApplicationDataCompositeValue)Settings.Values[compositeKey];
@@ -109,20 +146,21 @@ public T Read<T>(string compositeKey, string key, T @default = default)
                 string value = (string)composite[key];
                 if (value != null)
                 {
-                    return _serializer.Deserialize<T>(value);
+                    return Serializer.Deserialize<T>(value);
                 }
             }
 
             return @default;
         }
 
-        /// <inheritdoc />
-        public void Save<T>(string key, T value)
-        {
-            Settings.Values[key] = _serializer.Serialize(value);
-        }
-
-        /// <inheritdoc />
+        /// <summary>
+        /// Saves a group of items by its key in a composite.
+        /// This method should be considered for objects that do not exceed 8k bytes during the lifetime of the application
+        /// and for groups of settings which need to be treated in an atomic way.
+        /// </summary>
+        /// <typeparam name="T">Type of object saved.</typeparam>
+        /// <param name="compositeKey">Key of the composite (that contains settings).</param>
+        /// <param name="values">Objects to save.</param>
         public void Save<T>(string compositeKey, IDictionary<string, T> values)
         {
             if (KeyExists(compositeKey))
@@ -133,11 +171,11 @@ public void Save<T>(string compositeKey, IDictionary<string, T> values)
                 {
                     if (composite.ContainsKey(setting.Key))
                     {
-                        composite[setting.Key] = _serializer.Serialize(setting.Value);
+                        composite[setting.Key] = Serializer.Serialize(setting.Value);
                     }
                     else
                     {
-                        composite.Add(setting.Key, _serializer.Serialize(setting.Value));
+                        composite.Add(setting.Key, Serializer.Serialize(setting.Value));
                     }
                 }
             }
@@ -146,20 +184,18 @@ public void Save<T>(string compositeKey, IDictionary<string, T> values)
                 ApplicationDataCompositeValue composite = new ApplicationDataCompositeValue();
                 foreach (KeyValuePair<string, T> setting in values)
                 {
-                    composite.Add(setting.Key, _serializer.Serialize(setting.Value));
+                    composite.Add(setting.Key, Serializer.Serialize(setting.Value));
                 }
 
                 Settings.Values[compositeKey] = composite;
             }
         }
 
-        /// <inheritdoc />
-        public void Delete(string key)
-        {
-            Settings.Values.Remove(key);
-        }
-
-        /// <inheritdoc />
+        /// <summary>
+        /// Deletes a single item by its key in composite.
+        /// </summary>
+        /// <param name="compositeKey">Key of the composite (that contains settings).</param>
+        /// <param name="key">Key of the object.</param>
         public void Delete(string compositeKey, string key)
         {
             if (KeyExists(compositeKey))
@@ -169,20 +205,14 @@ public void Delete(string compositeKey, string key)
             }
         }
 
-        /// <inheritdoc />
-        public Task<bool> ItemExistsAsync(string itemName)
-        {
-            return ItemExistsAsync(Folder, itemName);
-        }
-
         /// <inheritdoc />
         public Task<T> ReadFileAsync<T>(string filePath, T @default = default)
         {
             return ReadFileAsync<T>(Folder, filePath, @default);
         }
 
         /// <inheritdoc />
-        public Task<IList<Tuple<DirectoryItemType, string>>> ReadFolderAsync(string folderPath)
+        public Task<IEnumerable<(DirectoryItemType, string)>> ReadFolderAsync(string folderPath)
         {
             return ReadFolderAsync(Folder, folderPath);
         }
@@ -205,18 +235,6 @@ public Task DeleteItemAsync(string itemPath)
             return DeleteItemAsync(Folder, itemPath);
         }
 
-        /// <summary>
-        /// Determine the existance of a file at the specified path.
-        /// To check for folders, use <see cref="ItemExistsAsync(string)" />.
-        /// </summary>
-        /// <param name="fileName">The name of the file.</param>
-        /// <param name="isRecursive">Whether the file should be searched for recursively.</param>
-        /// <returns>A task with the result of the file query.</returns>
-        public Task<bool> FileExistsAsync(string fileName, bool isRecursive = false)
-        {
-            return FileExistsAsync(Folder, fileName, isRecursive);
-        }
-
         /// <summary>
         /// Saves an object inside a file.
         /// </summary>
@@ -229,24 +247,13 @@ public Task<StorageFile> SaveFileAsync<T>(string filePath, T value)
             return SaveFileAsync<T>(Folder, filePath, value);
         }
 
-        private async Task<bool> ItemExistsAsync(StorageFolder folder, string itemName)
-        {
-            var item = await folder.TryGetItemAsync(itemName);
-            return item != null;
-        }
-
-        private Task<bool> FileExistsAsync(StorageFolder folder, string fileName, bool isRecursive)
-        {
-            return folder.FileExistsAsync(fileName, isRecursive);
-        }
-
         private async Task<T> ReadFileAsync<T>(StorageFolder folder, string filePath, T @default = default)
         {
             string value = await StorageFileHelper.ReadTextFromFileAsync(folder, filePath);
-            return (value != null) ? _serializer.Deserialize<T>(value) : @default;
+            return (value != null) ? Serializer.Deserialize<T>(value) : @default;
         }
 
-        private async Task<IList<Tuple<DirectoryItemType, string>>> ReadFolderAsync(StorageFolder folder, string folderPath)
+        private async Task<IEnumerable<(DirectoryItemType, string)>> ReadFolderAsync(StorageFolder folder, string folderPath)
         {
             var targetFolder = await folder.GetFolderAsync(folderPath);
             var items = await targetFolder.GetItemsAsync();
@@ -257,13 +264,13 @@ private async Task<IList<Tuple<DirectoryItemType, string>>> ReadFolderAsync(Stor
                     : item.IsOfType(StorageItemTypes.Folder) ? DirectoryItemType.Folder
                     : DirectoryItemType.None;
 
-                return new Tuple<DirectoryItemType, string>(itemType, item.Name);
+                return new ValueTuple<DirectoryItemType, string>(itemType, item.Name);
             }).ToList();
         }
 
         private Task<StorageFile> SaveFileAsync<T>(StorageFolder folder, string filePath, T value)
         {
-            return StorageFileHelper.WriteTextToFileAsync(folder, _serializer.Serialize(value)?.ToString(), filePath, CreationCollisionOption.ReplaceExisting);
+            return StorageFileHelper.WriteTextToFileAsync(folder, Serializer.Serialize(value)?.ToString(), filePath, CreationCollisionOption.ReplaceExisting);
         }
 
         private async Task CreateFolderAsync(StorageFolder folder, string folderPath)

Microsoft.Toolkit/Helpers/ObjectStorage/IFileStorageHelper.cs

@@ -18,13 +18,6 @@ namespace Microsoft.Toolkit.Helpers
     /// </summary>
     public interface IFileStorageHelper
     {
-        /// <summary>
-        /// Determines if a directory item already exists.
-        /// </summary>
-        /// <param name="itemName">Key of the file.</param>
-        /// <returns>True if an item exists.</returns>
-        Task<bool> ItemExistsAsync(string itemName);
-
         /// <summary>
         /// Retrieves an object from a file.
         /// </summary>
@@ -38,8 +31,8 @@ public interface IFileStorageHelper
         /// Retrieves the listings for a folder and the item types.
         /// </summary>
         /// <param name="folderPath">The path to the target folder.</param>
-        /// <returns>A list of file types and names in the target folder.</returns>
-        Task<IList<Tuple<DirectoryItemType, string>>> ReadFolderAsync(string folderPath);
+        /// <returns>A list of item types and names in the target folder.</returns>
+        Task<IEnumerable<(DirectoryItemType ItemType, string Name)>> ReadFolderAsync(string folderPath);
 
         /// <summary>
         /// Saves an object inside a file.

Microsoft.Toolkit/Helpers/ObjectStorage/IObjectSerializer.cs

@@ -2,6 +2,8 @@
 // The .NET Foundation licenses this file to you under the MIT license.
 // See the LICENSE file in the project root for more information.
 
+using System.Diagnostics.CodeAnalysis;
+
 namespace Microsoft.Toolkit.Helpers
 {
     /// <summary>
@@ -15,14 +17,16 @@ public interface IObjectSerializer
         /// <typeparam name="T">The type of the object to serialize.</typeparam>
         /// <param name="value">The object to serialize.</param>
         /// <returns>The serialized object.</returns>
-        object? Serialize<T>(T value);
+        [return: NotNullIfNotNull("value")]
+        string? Serialize<T>(T value);
 
         /// <summary>
-        /// Deserialize a primitive or string into an object of the given type.
+        /// Deserialize string into an object of the given type.
         /// </summary>
         /// <typeparam name="T">The type of the deserialized object.</typeparam>
         /// <param name="value">The string to deserialize.</param>
         /// <returns>The deserialized object.</returns>
-        T Deserialize<T>(object value);
+        [return: NotNullIfNotNull("value")]
+        T Deserialize<T>(string value);
     }
 }