Part 3 – The Troika : PowerShell, YAML and PowerShell Classes

  • In Part 1, we took YAML, converted it to PowerShell objects and then used PowerShell v5.0 to cast it to a class. This gave us runtime checking to see if we fat fingered entries in the YAML. This required very little coding, just some simple scaffold setup.

  • In Part 2, we took it further, easily making the variables know if they integers or not (for example) and with no work on our part, report an error if the YAML we typed was wrong. Plus, we saw how we could supply default values for fields not specified in the YAML. Streamling the authoring of the YAML information.

Checking for required data

In Part 3 we’ll take another step. We’ll see how we can make data required in the YAML that has been authored. Sometimes we forget it cause we move quickly other times we don’t specify because we don’t know about. In PowerShell we use [Parameter(Mandatory)] on parameters in a function to make this happen for example.

Let’s look again at the Purchaser example. Notice for Jane, the Age property is blank, because Age was not specified in the YAML.

Prints

This information may be critical for processing, so catching it and reporting it early is important. A fast feeback loop helps you correct problems more quickly. Plus, the sooner the missing data is detected, the less you have to undo downstream. Maybe this data is being inserted into a database. Name may get inserted first, then age. When the Jane record gets inserted the database my throw an error that age is null. Now you have to delete that record before running again.

Determining the missing age data early is good all around.

Added a Verification Method to the Data Class

Here’s one approach to check for data integrity. You’ll loop through all the data, here, the $Purchasers variable and check anything you is important. In this example, we’ll check for any purchasers age that is null, and if we find one, add a ‘message’ to the $dataError array. If we don’t find any missing data, $dataError is empty, we return it and use that to indicated no errors were found. This can be as sophisticated as you’d like to make it.

Using the Verification Method

After we cast the converted YAML into the $records variable. Call the Verify() method, capture the results in $verification and then check it. If its $null all is good, otherwise print out the errors.

Again, this can be as sophisticated as you want to make it. Use Write-Verbose, throw the error count and return the messages, or even log them.

Also, you can implement verification rules beyond checking for $null. You can check to see if data is in certain ranges, you can look up data in other data stores and make comparisons. Lots of flexibility.

Putting this all together, it will print this.

YAML Comments

One of the many things I like about YAML is that I can use comments. You can use comments to expalain parts or to tell ConvertFrom-YAML to skip over information. I much prefer that to deleting and re-adding it later.

In Closing

Here in Part 3 we see we can use PowerShell class methods to verify the data specified in the YAML. It’s a great way to enable a fast feeback loop for problems and keeping bad data out of downstream processes. We also see we can comments in YAML to add explanations and have data skipped. Tough to do in XML and JSON.

We’re not done yet, I’ll post some more about this approach.

Part 2 – The Troika : PowerShell, YAML and PowerShell Classes

In the last post The Troika : PowerShell, YAML and PowerShell Classes, we took YAML, converted it to PowerShell objects and then used PowerShell v5.0 to cast it to a class. This gave us runtime checking to see if we fat fingered entries in the YAML. This required very little coding, just some simple scaffold setup.

Once you do this, you’re a couple of steps from even more capability.

Note: Notice that using PowerShell v5.0 classes to do this work gives you intellisense in the console and editors.

Defaults and Types

In this example, the YAML has two Purchasers, and we left out Jane’s Age. When we convert, cast and print it, is shows up blank.

Prints

Lets set the type the $Age property in the Purchaser class to int.

Now, when we covert and cast, Jane’s age is now 0.

Prints

There’s another benfit to typing $Age. What if in the YAML we type a string for Jane’s age?

PowerShell handles checking the type and reporting a very useful error.

Doing Defaults

Going back the PowerShell class, you can set defaults for properties not defined in the YAML (Jane’s Age) and introduce new ones.

Note: Adding $DateCreated to the Purchaser class now makes it legal to use and overridden from the YAML.

Prints

Next steps

Now we’ve seen how we can convert YAML from a string (or file) into PowerShell and have a simple way to catch errors, correctly type the data, create defaults and easily introduce new properties.

In upcoming posts we’ll look at how to validate the YAML, for example, what if certain properties are required but not set?

The Troika : PowerShell, YAML and PowerShell Classes

YAML Ain’t Markup Language, its purpose is a data-oriented, rather than document markup. Combining this with PowerShell is potent, adding PowerShell classes, well its like adding bacon bits to bacon and eggs.

In this post, we’ll take it around the block.

Hello YAML

Key value pairs are easy, and we get a PowerShell object with property names.

Prints

Arrays

Now add an items property that creates an array. Use to create a collection of ordered value.

Note: YAML uses white space to indicate scoping of items

Prints

Let’s Get Complicated

Multi-nesting. Here we have a Purchaser with a MailingAddress and a State. Try to represent that using PSCustomObject and a HashTable.

Prints

Wait, there’s more

Now, what happens if you use these structures in your PowerShell scripts and someone fat fngers Age with AgeX. If you tried $r.Purchaser.Age, PowerShell would print nothing. This is where we add the bacon bits.

PowerShell Classes

Let’s introduce the Data class, cast $r to it, and print out the Purchaser.Age.

This buys us some intellisense when we type ([Data]$r). but we want some more saftey.

Let’s create a Purchaser class, add another purchaser and make an error by changing Age to AgeX.

Add the Purchaser Classe

Notice, we type the $Purchaser variable in the Data class as an array of Purchaser.

We also added Jane as and incorrectly specifed AgeX instead of Age.

Using a PowerShell class lets us find errors early in the process and without any coding logic on our part.

Prints

A lot of Potential

This can be applied to many scenarios. Having a data oriented human-readble file that can be easily used in PowerShell and have it’s structure easily validated is tremendous.

In future posts we’ll kick it up a few notches.