ObjectStorage enhancements

[shweaver-MSFT]

Fixes #3903

PR Type

What kind of change does this PR introduce?

• Feature

What is the current behavior?

The ObjectStorage helper interfaces and implementations currently live in the *.Uwp package. This means that they are not consumable from NetStandard projects, such as the CommunityToolkit.Graph package.

In addition, the IObjectStorageHelper is a mixture of support for both dictionary style settings storage, with some file storage features as well. Currently, supporting both file and folder scenarios is odd/difficult for storage endpoints that don't operate in a similar manner to Windows.Storage.ApplicationData.

Lastly, the support for file storage in IObjectStorageHelper is not complete and missing some basic CRUD operations that can make it difficult to work with in real-world application scenarios.

What is the new behavior?

I've done a few things:

1. Deprecated the existing structures in the Microsoft.Toolkit.Uwp/Helpers/ObjectStorage folder:

   • BaseObjectStorageHelper
   • IObjectSerializer
   • IObjectStorageHelper
   • LocalObjectStorageHelper
   • SystemSerializer

2. Migrated some of the previous structures up into the Microsoft.Toolkit/Helpers/ObjectStorage folder so that they are consumable from NetStandard:

   • IObjectSerializer
   • SystemSerializer

3. Created new interfaces to replace the functionality defined in the now defunct IObjectStorageHelper:

   • ISettingsStorageHelper - Interop with values as key/value pairs, like a dictionary.
   • IFileStorageHelper - Interop with a file system to store values in files and folders.

4. Replaced the functionality provided by BaseObjectStorageHelper and LocalObjectStorageHelper with an implementation of ISettingsStorageHelper and IFileStorageHelper:

   • ApplicationDataStorageHelper - Interop with local settings and files through Windows.Storage.ApplicationData.

Use it like so:

ApplicationDataStorageHelper appDataStorageHelper = ApplicationDataStorageHelper.GetCurrent(new Toolkit.Helpers.SystemSerializer());

// Save and Read simple objects
string keySimpleObject = "simple";
appDataStorageHelper.Save(keySimpleObject, 42);
appDataStorageHelper.TryRead<string>(keySimpleObject, out string result);

// Save and Read complex objects
string complexObjectKey = "complexObject";
await appDataStorageHelper.SaveFileAsync(complexObjectKey, new MyComplexObject());
var complexObject = await appDataStorageHelper.ReadFileAsync<MyComplexObject>(complexObjectKey);

// Complex object example
public class MyComplexObject
{
    public string MyContent { get; set; }
    public List<string> MyContents { get; set; }
    public List<MyComplexObject> MyObjects { get; set; }
}

Altogether, this provides a transition path from the previous ObjectStorage constructs to a more granular set of interfaces with identical signatures plus enhanced support for file and folder CRUD operations.

PR Checklist

Please check if your PR fulfills the following requirements:

• Tested code with current supported SDKs
• Pull Request has been submitted to the documentation repository instructions. Link:
• Sample in sample app has been added / updated (for bug fixes / features)
  • Icon has been created (if new sample) following the Thumbnail Style Guide and templates
• New major technical changes in the toolkit have or will be added to the Wiki e.g. build changes, source generators, testing infrastructure, sample creation changes, etc...
• Tests for the changes have been added (for bug fixes / features) (if applicable)
• Header has been added to all new source files (run build/UpdateHeaders.bat)
• Contains NO breaking changes

Other information

Looking for feedback!

[ghost]

Thanks shweaver-MSFT for opening a Pull Request! The reviewers will test the PR and highlight if there is any conflict or changes required. If the PR is approved we will proceed to merge the pull request 🙌

[michael-hawker]

Awesome start @shweaver-MSFT! Thanks! 🎉🎉🎉 This is going to be Epic!

Glad everything is pretty much just drop-over and replace for existing users, that's amazing. Really like how that all came together and the extra thought you put into how these things get split, combined again, and a few of the missing features.

I did throw some curve-balls questions into the IFileStorageHelper discussion now that it's going to open up potential implementations on other platforms. Also maybe identified a couple of gaps. So let's just work through making sure we can solidify any assumptions there and document how things should behave for other future implementations (hopefully our existing UWP and OneDrive based implementations should provide enough context for what's reasonable for a File System to be able to do and what it should provide).

I think all that is mostly additive though, so we should still be pretty close. 🎉

[ghost]

This PR has been marked as "needs attention 👋" and awaiting a response from the team.

[shweaver-MSFT]

@michael-hawker I think I've responded to everything, let me know if I missed something.

I had zero luck getting the nuget package from the PR feed working yesterday, so I'll try again once the latest build completes and spits out a new package

[michael-hawker]

Closing and re-opening to retrigger build with org name change.

[ghost]

This PR has been marked as "needs attention 👋" and awaiting a response from the team.

[michael-hawker]

Build errors:

 D:\a\1\s\Microsoft.Toolkit.Uwp\Helpers\ObjectStorage\ApplicationDataStorageHelper.cs(25,96): error CS8632: The annotation for nullable reference types should only be used in code within a '#nullable' annotations context. [D:\a\1\s\Microsoft.Toolkit.Uwp\Microsoft.Toolkit.Uwp.csproj]
         D:\a\1\s\Microsoft.Toolkit.Uwp\Helpers\ObjectStorage\ApplicationDataStorageHelper.cs(37,124): error CS8632: The annotation for nullable reference types should only be used in code within a '#nullable' annotations context. [D:\a\1\s\Microsoft.Toolkit.Uwp\Microsoft.Toolkit.Uwp.csproj]
         D:\a\1\s\Microsoft.Toolkit.Uwp\Helpers\ObjectStorage\ApplicationDataStorageHelper.cs(68,103): error CS8632: The annotation for nullable reference types should only be used in code within a '#nullable' annotations context. [D:\a\1\s\Microsoft.Toolkit.Uwp\Microsoft.Toolkit.Uwp.csproj]

FYI @Sergio0694 there seem to be a lot of build warnings in the azure pipeline for t he Unit Tests for the Source Generators and some things for the HighPerformance package?

[Sergio0694]

"there seem to be a lot of build warnings in the azure pipeline for t he Unit Tests for the Source Generators and some things for the HighPerformance package?"

@michael-hawker thanks for the heads up! I've opened #4142 to fix them 😄

[ghost]

This PR has been marked as "needs attention 👋" and awaiting a response from the team.

[michael-hawker]

@Sergio0694 @shweaver-MSFT everything set now on this PR once it builds?

[shweaver-MSFT]

@Sergio0694 @shweaver-MSFT everything set now on this PR once it builds?

I believe it is!

[Sergio0694]

Wo-hooooo!! 🎉🎉🎉

[ghost]

Hello @michael-hawker!

Because this pull request has the auto merge :zap: label, I will be glad to assist with helping to merge this pull request once all check-in policies pass.

p.s. you can customize the way I help with merging this pull request, such as holding this pull request until a specific person approves. Simply @mention me (@msftbot) and give me an instruction to get started! Learn more here.

[shweaver-MSFT]

🎉🎉🎉 Woot!