Finally, Introducing the First Preview of BurntToast v1

Posted on February 12, 2022 • 4 minutes • 735 words

Evidently, this last year has gone by very fast. I announced that I was starting to work on the re-write of BurntToast that will be released as v1 back in April of 2021 and then promptly… didn’t get around to working on it. With a job change and generally being busy, BurntToast took a back seat for a while there.

But I’m glad to say that the first preview release is up on the PowerShell Gallery: BurntToast 1.0.0-Preview1 .

What’s New?

As I’ve said before, this is going to be an almost complete re-write of the module. How it’s used is going to change, both because the upstream .NET resources have enabled slicker experiences and also the benefit of having made my own UX mistakes in previous versions that I’ve always wanted a do-over on.

To that end, this first preview release is very limited, featuring only a small handful of functions:

If you’ve used the current versions of BurntToast, you’ll notice a lack of functions with the New verb. Almost everything in v0.8.5 , and earlier, results in an object, be that a “text” object or an “image” object. The whole thing relied on you knowing how and where to use those objects.

That’s all well and good if you’ve got a good understanding of the underlying XML , but arcane if you don’t. Where, for example, does the “binding” object fit? How is it different to the “visual” object?

The difference with v1 is that it all revolves around a single object, the “Toast Content Builder” which you create with the New-BTContentBuilder function. You take that and build your toast on top of it by adding elements to it.

A Tale of Two Usage Models

This first set of functions were chosen as a good show case for the new usage of the BurntToast module. With them you can create visually interesting toasts quickly, without getting bogged down with too many advanced options (for now.)

For example, this toast was created using the available commands and just five lines of code:

The first method for doing this with BurntToast v1 is to store the Toast Content Builder in a variable and pass it into each command in turn until you’re ready to display it using the Show-BTNotification function.

$Builder = New-BTContentBuilder
$Builder | Add-BTAppLogo
$Builder | Add-BTText "BurntToast v1 is in the works!", "It took a while, but progress is being made"
$Builder | Add-BTImage "https://raw.githubusercontent.com/Windos/BurntToast/main/Media/BurntToast-Wide.png"
$Builder | Show-BTNotification

Having to specify the Toast Content Builder all the time is a bit of a drag, right? That’s why each of the functions with the Add verb supports a PassThru parameter that outputs the updated builder object.

You could add this to each command, and pipe through each command.

New-BTContentBuilder |
    Add-BTAppLogo -PassThru |
    Add-BTText "BurntToast v1 is in the works!", "It took a while, but progress is being made" -PassThru |
    Add-BTImage "https://raw.githubusercontent.com/Windos/BurntToast/main/Media/BurntToast-Wide.png" -PassThru |
    Show-BTNotification

That’s better, but having to specify -PassThru all the time is a bit of a drag. Instead, you can use a default parameter value to say it should always be used for any function starting with Add-BT.

$PSDefaultParameterValues = @{
    "Add-BT*:PassThru" = $true
}

New-BTContentBuilder |
    Add-BTAppLogo |
    Add-BTText "BurntToast v1 is in the works!", "It took a while, but progress is being made" |
    Add-BTImage "https://raw.githubusercontent.com/Windos/BurntToast/main/Media/BurntToast-Wide.png" |
    Show-BTNotification

You Feedback Needed

You’ll note that there’s three functions included in this preview that deal with different types of images:

Regular images that show in the body of a notification, under any text.
Hero images that show as large, bold, banners across the top of a notification.
App logos, which are generally the icon for the app generating a notification or possibly a user avatar for chat notifications (for example)

These functions are all very similar and could be a single command, like they are in the pre v1 BurntToast versions.

Chances are Preview2 will roll these into one function. If you have opinions for either option, I want to hear from you. Please do drop your thoughts into this discussion .

Your feedback on any other issue is also very much appreciated, so don’t hesitate to get in touch outside of that particular discussion too!

For now, please try out the current preview and keep your eye out for the next one.

Credit

Hero image by Ross Findon on Unsplash .