Review of the "Essentials" interface API

[mattleibow]

Description of Change

As I was working through #5562, I noticed that as a result of the first pass of the Essentials API from statics to interfaces, we did not correctly updated the initial changes.

There are several cases where the API of the interface was geared towards swapping out the implementation of the static API:

interface IClipboard {
    Task<string> GetTextAsync();
    void StartListeners();
    void StopListeners();
}

However, this is incorrect and unhelpful in the new world where the interface is supposed to be self contained an mockable:

interface IClipboard {
    Task<string> GetTextAsync();
    event EventHandler<EventArgs> ClipboardContentChanged;
}

API Changes

Originally we were going to make the new API be instance based and remove (then we changed to just obsolete) the static methods, however, this is a massive change and no benefit. Sure, it is a bit weird to have a Accelerometer.Start() AND Accelerometer.Default.Start(), however, as can be seen from the diff - this means no code changes for anyone that was using essentials and then Maui.

However, with the work we have been doing with these APIs over the month, we now have a useful as well as "opt-in" way of using essentials.

Previously there was no way to mock/test using essentials, and thus you either had to roll your own abstraction or get someone else to do it.

Now, we have all that work in the box, thanks to several PRs and adjustments. And no code changes for existing usage.

Static APIs

If you are writing a simple app and don't believe in testing, you can write code like this using the static APIs Geolocation.GetLocationAsync():

class MyViewModel
{
    public async Task UploadLocationAsync()
    {
        var location = await Geolocation.GetLocationAsync();
        var uploader = MyUploader();
        await uploader.UploadLocationAsync(location);
    }
}

Instance / DI-Friendly APIs

However, if you want to create a testable system or use DI, you now can using the instance APIs Geolocation.Default.GetLocationAsync():

class MyViewModel
{
    public MyViewModel(IGeolocation geolocation, IUploader uploader)
    {
        // TODO: set fields
    }

    public async Task UploadLocationAsync()
    {
        var location = await deolocation.GetLocationAsync();
        await uploader.UploadLocationAsync(location);
    }
}

Now you an also use DI or write tests:

async Task TheBigTest()
{
    var vm = new MyViewModel(new StubGeolocation(), new StubUploader());
    await UploadLocationAsync();

    // TODO: assert location was retrieved and then uploaded
}

[Redth]

@mattleibow I wonder if we still want all the Implementation classes to live in the .Implementation namespace?

[mattleibow]

Right now I am moving them internal and back into the nice namespace.

In net7 we can figure out a nice way for users to set this.

The plan now is to make Accelerometer.Default return the OS accelerometer, but via an interface. If you want code to be testable, do t use the static in vms, use the interface and DI using .Default.

Think of the static as a way to get the OS instance, but in reality you need to make your apis testable, not our initial idea to make the core OS testable.

See for example things starting with A to F. Done that half first and will continue tomorrow.

[Redth]

I missed that you made them internal, that works for me for net6 timeframe