Merge branch 'main' into winui

# Conflicts:
#	CommunityToolkit.Common/Extensions/ISettingsStorageHelperExtensions.cs
#	CommunityToolkit.Common/Helpers/ObjectStorage/DirectoryItemType.cs
#	CommunityToolkit.Common/Helpers/ObjectStorage/IFileStorageHelper.cs
#	CommunityToolkit.Common/Helpers/ObjectStorage/IObjectSerializer.cs
#	CommunityToolkit.Common/Helpers/ObjectStorage/ISettingsStorageHelper.cs
#	CommunityToolkit.Common/Helpers/ObjectStorage/SystemSerializer.cs
#	CommunityToolkit.WinUI.SampleApp/Controls/SampleAppMarkdownRenderer.cs
#	CommunityToolkit.WinUI.SampleApp/Models/Sample.cs
#	CommunityToolkit.WinUI.SampleApp/Models/Samples.cs
#	CommunityToolkit.WinUI.SampleApp/SamplePages/Object Storage/ObjectStoragePage.xaml.cs
#	CommunityToolkit.WinUI.UI.Controls.Layout/ListDetailsView/ListDetailsView.cs
#	CommunityToolkit.WinUI/Helpers/ObjectStorage/ApplicationDataStorageHelper.CacheFolder.cs
#	CommunityToolkit.WinUI/Helpers/ObjectStorage/ApplicationDataStorageHelper.cs
#	CommunityToolkit.WinUI/Helpers/ObjectStorage/IObjectSerializer.cs
#	CommunityToolkit.WinUI/Helpers/SystemInformation.cs
#	UnitTests/UnitTests.UWP/UnitTests.UWP.csproj
#	azure-pipelines.yml
#	build/StyleXaml.bat
#	build/UpdateHeaders.bat
#	build/build.cake
#	build/build.ps1

Author: azchohfi

.gitattributes

@@ -17,7 +17,7 @@
 #
 # Merging from the command prompt will add diff markers to the files if there
 # are conflicts (Merging from VS is not affected by the settings below, in VS
-# the diff markers are never inserted). Diff markers may cause the following 
+# the diff markers are never inserted). Diff markers may cause the following
 # file extensions to fail to load in VS. An alternative would be to treat
 # these files as binary and thus will always conflict and require user
 # intervention with every merge. To do so, just uncomment the entries below
@@ -46,9 +46,9 @@
 
 ###############################################################################
 # diff behavior for common document formats
-# 
+#
 # Convert binary document formats to text before diffing them. This feature
-# is only available from the command line. Turn it on by uncommenting the 
+# is only available from the command line. Turn it on by uncommenting the
 # entries below.
 ###############################################################################
 #*.doc   diff=astextplain

CommunityToolkit.Common/CommunityToolkit.Common.csproj

@@ -21,9 +21,10 @@
     <DefineConstants>NETSTANDARD2_1_OR_GREATER</DefineConstants>
   </PropertyGroup>
 
-  <!-- .NET Standard 1.4 doesn't have the [Pure] attribute -->
+  <!-- .NET Standard 1.4 doesn't have the [Pure] attribute or ValueTuple -->
   <ItemGroup Condition="'$(TargetFramework)' == 'netstandard1.4'">
     <PackageReference Include="System.Diagnostics.Contracts" Version="4.3.0" />
+    <PackageReference Include="System.ValueTuple" Version="4.5.0" />
   </ItemGroup>
 
 </Project>

CommunityToolkit.Common/Extensions/ISettingsStorageHelperExtensions.cs

@@ -0,0 +1,84 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// 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;
+using System.Collections.Generic;
+using System.Text;
+using CommunityToolkit.Common.Helpers;
+
+namespace CommunityToolkit.Common.Extensions
+{
+    /// <summary>
+    /// Helpers methods for working with <see cref="ISettingsStorageHelper{TKey}"/> implementations.
+    /// </summary>
+    public static class ISettingsStorageHelperExtensions
+    {
+        /// <summary>
+        /// Attempts to read the provided key and return the value.
+        /// If the key is not found, the fallback value will be used instead.
+        /// </summary>
+        /// <typeparam name="TKey">The type of key used to lookup the object.</typeparam>
+        /// <typeparam name="TValue">The type of object value expected.</typeparam>
+        /// <param name="storageHelper">The storage helper instance fo read from.</param>
+        /// <param name="key">The key of the target object.</param>
+        /// <param name="fallback">An alternative value returned if the read fails.</param>
+        /// <returns>The value of the target object, or the fallback value.</returns>
+        public static TValue? GetValueOrDefault<TKey, TValue>(this ISettingsStorageHelper<TKey> storageHelper, TKey key, TValue? fallback = default)
+            where TKey : notnull
+        {
+            if (storageHelper.TryRead<TValue>(key, out TValue? storedValue))
+            {
+                return storedValue;
+            }
+            else
+            {
+                return fallback;
+            }
+        }
+
+        /// <summary>
+        /// Read the key in the storage helper instance and get the value.
+        /// </summary>
+        /// <typeparam name="TKey">The type of key used to lookup the object.</typeparam>
+        /// <typeparam name="TValue">The type of object value expected.</typeparam>
+        /// <param name="storageHelper">The storage helper instance fo read from.</param>
+        /// <param name="key">The key of the target object.</param>
+        /// <returns>The value of the target object</returns>
+        /// <exception cref="KeyNotFoundException">Throws when the key is not found in storage.</exception>
+        public static TValue? Read<TKey, TValue>(this ISettingsStorageHelper<TKey> storageHelper, TKey key)
+            where TKey : notnull
+        {
+            if (storageHelper.TryRead<TValue>(key, out TValue? value))
+            {
+                return value;
+            }
+            else
+            {
+                ThrowKeyNotFoundException(key);
+                return default;
+            }
+        }
+
+        /// <summary>
+        /// Deletes a key from storage.
+        /// </summary>
+        /// <typeparam name="TKey">The type of key used to lookup the object.</typeparam>
+        /// <param name="storageHelper">The storage helper instance to delete from.</param>
+        /// <param name="key">The key of the target object.</param>
+        /// <exception cref="KeyNotFoundException">Throws when the key is not found in storage.</exception>
+        public static void Delete<TKey>(this ISettingsStorageHelper<TKey> storageHelper, TKey key)
+            where TKey : notnull
+        {
+            if (!storageHelper.TryDelete(key))
+            {
+                ThrowKeyNotFoundException(key);
+            }
+        }
+
+        private static void ThrowKeyNotFoundException<TKey>(TKey key)
+        {
+            throw new KeyNotFoundException($"The given key '{key}' was not present");
+        }
+    }
+}

CommunityToolkit.Common/Helpers/ObjectStorage/DirectoryItemType.cs

@@ -0,0 +1,27 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+// See the LICENSE file in the project root for more information.
+
+namespace CommunityToolkit.Common.Helpers
+{
+    /// <summary>
+    /// Represents the types of items available in a directory.
+    /// </summary>
+    public enum DirectoryItemType
+    {
+        /// <summary>
+        /// The item is neither a file or a folder.
+        /// </summary>
+        None,
+
+        /// <summary>
+        /// Represents a file type item.
+        /// </summary>
+        File,
+
+        /// <summary>
+        /// Represents a folder type item.
+        /// </summary>
+        Folder
+    }
+}

CommunityToolkit.Common/Helpers/ObjectStorage/IFileStorageHelper.cs

@@ -0,0 +1,60 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// 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;
+using System.Collections.Generic;
+using System.Threading.Tasks;
+
+namespace CommunityToolkit.Common.Helpers
+{
+    /// <summary>
+    /// Service interface used to store data in a directory/file-system via files and folders.
+    ///
+    /// This interface is meant to help abstract file storage operations across platforms in a library,
+    /// but the actual behavior will be up to the implementer. Such as, we don't provide a sense of a current directory,
+    /// so an implementor should consider using full paths to support any file operations. Otherwise, a "directory aware"
+    /// implementation could be achieved with a current directory field and traversal functions, in which case relative paths would be applicable.
+    /// </summary>
+    public interface IFileStorageHelper
+    {
+        /// <summary>
+        /// Retrieves an object from a file.
+        /// </summary>
+        /// <typeparam name="T">Type of object retrieved.</typeparam>
+        /// <param name="filePath">Path to the file that contains the object.</param>
+        /// <param name="default">Default value of the object.</param>
+        /// <returns>Waiting task until completion with the object in the file.</returns>
+        Task<T?> ReadFileAsync<T>(string filePath, T? @default = default);
+
+        /// <summary>
+        /// 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 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.
+        /// </summary>
+        /// <typeparam name="T">Type of object saved.</typeparam>
+        /// <param name="filePath">Path to the file that will contain the object.</param>
+        /// <param name="value">Object to save.</param>
+        /// <returns>Waiting task until completion.</returns>
+        Task CreateFileAsync<T>(string filePath, T value);
+
+        /// <summary>
+        /// Ensure a folder exists at the folder path specified.
+        /// </summary>
+        /// <param name="folderPath">The path and name of the target folder.</param>
+        /// <returns>Waiting task until completion.</returns>
+        Task CreateFolderAsync(string folderPath);
+
+        /// <summary>
+        /// Deletes a file or folder item.
+        /// </summary>
+        /// <param name="itemPath">The path to the item for deletion.</param>
+        /// <returns>Waiting task until completion.</returns>
+        Task DeleteItemAsync(string itemPath);
+    }
+}

CommunityToolkit.Common/Helpers/ObjectStorage/IObjectSerializer.cs

@@ -0,0 +1,28 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+// See the LICENSE file in the project root for more information.
+
+namespace CommunityToolkit.Common.Helpers
+{
+    /// <summary>
+    /// A basic serialization service.
+    /// </summary>
+    public interface IObjectSerializer
+    {
+        /// <summary>
+        /// Serialize an object into a string. It is recommended to use strings as the final format for objects.
+        /// </summary>
+        /// <typeparam name="T">The type of the object to serialize.</typeparam>
+        /// <param name="value">The object to serialize.</param>
+        /// <returns>The serialized object.</returns>
+        string? Serialize<T>(T value);
+
+        /// <summary>
+        /// 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>(string value);
+    }
+}

CommunityToolkit.Common/Helpers/ObjectStorage/ISettingsStorageHelper.cs

@@ -0,0 +1,45 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// 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.Collections.Generic;
+
+namespace CommunityToolkit.Common.Helpers
+{
+    /// <summary>
+    /// Service interface used to store data using key value pairs.
+    /// </summary>
+    /// <typeparam name="TKey">The type of keys to use for accessing values.</typeparam>
+    public interface ISettingsStorageHelper<in TKey>
+        where TKey : notnull
+    {
+        /// <summary>
+        /// Retrieves a single item by its key.
+        /// </summary>
+        /// <typeparam name="TValue">Type of object retrieved.</typeparam>
+        /// <param name="key">Key of the object.</param>
+        /// <param name="value">The <see typeparamref="TValue"/> object for <see typeparamref="TKey"/> key.</param>
+        /// <returns>A boolean indicator of success.</returns>
+        bool TryRead<TValue>(TKey key, out TValue? value);
+
+        /// <summary>
+        /// Saves a single item by its key.
+        /// </summary>
+        /// <typeparam name="TValue">Type of object saved.</typeparam>
+        /// <param name="key">Key of the value saved.</param>
+        /// <param name="value">Object to save.</param>
+        void Save<TValue>(TKey key, TValue value);
+
+        /// <summary>
+        /// Deletes a single item by its key.
+        /// </summary>
+        /// <param name="key">Key of the object.</param>
+        /// <returns>A boolean indicator of success.</returns>
+        bool TryDelete(TKey key);
+
+        /// <summary>
+        /// Clear all keys and values from the settings store.
+        /// </summary>
+        void Clear();
+    }
+}

CommunityToolkit.Common/Helpers/ObjectStorage/SystemSerializer.cs

@@ -0,0 +1,46 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// 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;
+using System.Reflection;
+
+namespace CommunityToolkit.Common.Helpers
+{
+    /// <summary>
+    /// A bare-bones serializer which knows how to deal with primitive types and strings only.
+    /// It is recommended for more complex scenarios to implement your own <see cref="IObjectSerializer"/> based on System.Text.Json, Newtonsoft.Json, or DataContractJsonSerializer see https://aka.ms/wct/storagehelper-migration
+    /// </summary>
+    public class SystemSerializer : IObjectSerializer
+    {
+        /// <summary>
+        /// Take a primitive value from storage and return it as the requested type using the <see cref="Convert.ChangeType(object, Type)"/> API.
+        /// </summary>
+        /// <typeparam name="T">Type to convert value to.</typeparam>
+        /// <param name="value">Value from storage to convert.</param>
+        /// <returns>Deserialized value or default value.</returns>
+        public T Deserialize<T>(string value)
+        {
+            var type = typeof(T);
+            var typeInfo = type.GetTypeInfo();
+
+            if (typeInfo.IsPrimitive || type == typeof(string))
+            {
+                return (T)Convert.ChangeType(value, type);
+            }
+
+            throw new NotSupportedException("This serializer can only handle primitive types and strings. Please implement your own IObjectSerializer for more complex scenarios.");
+        }
+
+        /// <summary>
+        /// Returns the value so that it can be serialized directly.
+        /// </summary>
+        /// <typeparam name="T">Type to serialize from.</typeparam>
+        /// <param name="value">Value to serialize.</param>
+        /// <returns>String representation of value.</returns>
+        public string? Serialize<T>(T value)
+        {
+            return value?.ToString();
+        }
+    }
+}

CommunityToolkit.WinUI.SampleApp/Controls/SampleAppMarkdownRenderer.cs

@@ -5,6 +5,7 @@
 using System;
 using System.Collections.Generic;
 using System.Linq;
+using CommunityToolkit.Common.Helpers;
 using CommunityToolkit.Common.Parsers.Markdown;
 using CommunityToolkit.Common.Parsers.Markdown.Blocks;
 using CommunityToolkit.Common.Parsers.Markdown.Inlines;
@@ -407,19 +408,19 @@ public string DesiredLang
         {
             get
             {
-                return storage.Read<string>(DesiredLangKey);
+                return settingsStorage.Read<string>(DesiredLangKey);
             }
 
             set
             {
-                storage.Save(DesiredLangKey, value);
+                settingsStorage.Save(DesiredLangKey, value);
             }
         }
 
         /// <summary>
-        /// The Local Storage Helper.
+        /// The local app data storage helper for storing settings.
         /// </summary>
-        private LocalObjectStorageHelper storage = new LocalObjectStorageHelper(new SystemSerializer());
+        private readonly ApplicationDataStorageHelper settingsStorage = ApplicationDataStorageHelper.GetCurrent();
 
         /// <summary>
         /// DocFX note types and styling info, keyed by identifier.

CommunityToolkit.WinUI.SampleApp/Models/Sample.cs

@@ -20,6 +20,7 @@
 // TODO Reintroduce graph controls
 // using CommunityToolkit.Graph.Converters;
 // using CommunityToolkit.Graph.Providers;
+using CommunityToolkit.Common.Helpers;
 using CommunityToolkit.WinUI.Helpers;
 using CommunityToolkit.WinUI.Input.GazeInteraction;
 using CommunityToolkit.WinUI.SampleApp.Models;
@@ -44,7 +45,7 @@ public class Sample
 
         public static async void EnsureCacheLatest()
         {
-            var settingsStorage = new LocalObjectStorageHelper(new SystemSerializer());
+            var settingsStorage = ApplicationDataStorageHelper.GetCurrent();
 
             var onlineDocsSHA = await GetDocsSHA();
             var cacheSHA = settingsStorage.Read<string>(_cacheSHAKey);