[WIP/QRCoder2] Fluent API experimentation PR

[Shane32]

Summary

Experimentation with fluent API syntax

Samples

var code = QRCodeBuilder.CreateEmail("test@microsoft.com")
    .WithSubject("Testing")
    .WithBody("Hello World!")
    .WithErrorCorrection(QRCodeGenerator.ECCLevel.H)
    .RenderWith<AsciiRenderer>()
    .WithQuietZone(false)
    .ToString();

var image = QRCodeBuilder.CreatePhoneNumber("1234567890")
    .WithErrorCorrection(QRCodeGenerator.ECCLevel.H)
    .RenderWith<SystemDrawingRenderer>(20)
    .WithQuietZone(false)
    .ToBitmap();

var base64 = QRCodeBuilder.CreateMMS("1234567890", "Hello")
    .RenderWith<PngRenderer>()
    .ToBase64String();

Intellisense samples

Preliminary Findings

1. Could start with new QRCodeBuilder.Email("test@microsoft.com") rather than QRCodeBuilder.CreateEmail("test@microsoft.com") - which is pretty similar to the existing new PayloadGenerator.Wifi() syntax actually, with the difference being the fluent syntax for configuration. One benefit of using new is that additional payloads can be added by simply adding a new class into the correct namespace. Whereas methods cannot be added to QRCodeBuilder outside of QRCoder.
2. Using RenderWith<T> breaks the intellisense pattern because T does not give a list of the specific renderers available. Probably better to create an extension method for each renderer, like RenderAsAscii() and RenderAsPng(20) instead
3. RenderWith<T> does not allow for render-specific constructor parameters. I've compensated with support for only two patterns: (1) no arguments (2) pixels per module argument. Having RenderAs...() dedicated methods would allow each renderer to require specific arguments.
4. The builder syntax could likely be added to v1.x as a new layer, as shown in this PR, with any implementation changes we wish to make within the builder methods. Then v2 just removes (or makes internal) all the old methods.
5. The new builders, when layered on the old code, are quite easy to write. Once the old code is removed, additional optimizations can be added to enhance trimming support. This trimming capability may consolidate the QRCode and ArtQRCode classes.
6. All of the supporting code can be nested as deep within namespaces as desired, since intellisense always provides the correct context-sensitive methods. Except for RenderWith<T>, as noted in item 2 above. Another reason to use RenderAsAscii() or similar.
7. The extension methods on the renderers (ToArray, ToStream, ToFile, etc) are really cool -- each renderer need only implement ToStream and all the other methods are available via extension methods. Similar functionality for text renderers; even with only implementing ToString they can also provide ToFile, ToStream, ToBase64, and so on via extension methods.

[Shane32]

Sample where the ctor only has the email address, and the subject/body are provided by extension methods. Realistically, I'm thinking that the required or common parameters always appear in the constructor (or as an overload), but all of the optional/rare options (like MailEncoding) are extension methods.

[Shane32]

We can use this class for any payload that immediately serializes to a string value. At least if we design it like CreateUrl(...). Of course it would be nearly as easy to have additional classes for each payload type, similar to how it is now, if we want new QRCodeBuilder.Url(...) or whatnot.

[Shane32]

The idea here is that while most all payloads can inherit from PayloadBase and inherit some configurable settings, perhaps some payloads, like the swiss banking payload, does not support configuring the Eci mode or whatever. Or, we can override some of these properties to add validation, for instance ensuring that a certain minimum ECC level is maintained. There's a number of ways to actually implement this, all with similar end results.

[Shane32]

These interfaces are always explicitly implemented so that they do not appear on the intellisense list of accessible members for the class. Rather, the extension method will appear, which uses generics to return the same type.

If that's confusing, for example, this code would break the fluent syntax:

public PayloadBase WithEciMode(EciMode value)
{
    _eciMode = value;
}

Because it returns the base class type (PayloadBase), rather than the type of the derived type (e.g. WiFiPayload). Extension methods allow the intended behavior, while eliminating duplicate code across each payload class.

[Shane32]

This functions, but I think explicit extension methods such as RenderWithAsciiRenderer() or RenderAsPng() would be better than generics here. I specifically don't like that intellisense does not show the compatible renderers for T. Sorta breaks the goal.

[Shane32]

Concept is that all byte-array-type renderers (or ones that can serialize to a byte array) implement this interface. If they use a MemoryStream under the hood, it's a direct pass-through. If they generate a byte array directly, then wrapping it in a MemoryStream is quite inexpensive, as it does not duplicate the entire byte array.

[Shane32]

And here we can extract the original array without duplicating it.

[Shane32]

Concept is that all string-based renderers (Ascii, Svg) implement this interface. Another option would be to have it implement ToStringBuilder instead, more similar to IStreamRenderer above. However, we can't create an extension method called ToString because object.ToString() would always take precedence over an extension method.

[Shane32]

Renderers which return a specialized type may optionally also implement IStreamRenderer as is shown here. Then ToFile and other extension methods for byte-array type renderers are available.

[Shane32]

Another option would be to store the IPayload object itself. I opted to call ToMatrix immediately, so if there were any exceptions while converting the payload to a module matrix, it would be caught at this point, enhancing the ability to diagnose faulty fluent syntax.

[Shane32]

Note that if any renderer wanted to optimize something like ToFile, they could implement the method directly, which takes precedence over extension methods.

[csturm83]

The builder syntax could likely be added to v1.x as a new layer, as shown in this PR

QRCoder2.FluentExtensions maybe? 😉

[codebude]

Hi Shane, thanks for the PR. That looks pretty interesting. However, I don't want to merge this into v1.x, but would like to include it in v2 first, as I don't want to make/document/communicate any more major API changes to v1. I hope that's okay with you.

[Shane32]

Certainly. I wrote this more of a discussion/preview/review of a potential approach.