DEV Community: TheInfraDev

Powershell: Build Configuration Objects - part 2 of 3

TheInfraDev — Sat, 16 Feb 2019 04:38:30 +0000

PowerShell Functions and Classes Pt 2 - Build Configuration Objects

Note: This is part two of a three part series on PowerShell Classes and Functions.

In part one we looked at how we can create a class to hold our configuration object. We then created a constructor to create some automation in our config. In the second part I want to look into how we can use methods to generate our objects. For example, lets take our last example of a TV Gaming PC.


Class PCSystem
{
        [string]$CPU
        [string]$Mainboard   = 'MSI B450M Mortar Titanium'
        [string]$Case        = 'Thermaltake Level 20 VT Chassis'
        [string]$PowerSupply = 'SeaSonic FocusPlus Gold 650W'
        [string]$RAM         = 'Team Delta RGB - 16 GB DDR3000'
        [string]$Storage     = 'Samsung 970 EVO 500 GB'
        [string]$GPU
}

We have deliberately left the CPU and GPU options available to be tweaked as these are the main configuration changes we can make to our performance. I would like to be able to configure it with the following options:

1 : CPU = 'AMD Ryzen 5 2400G' | GPU = 'No GPU'

2 : CPU = 'AMD Ryzen 3 2200G' | GPU = 'EVGA - GeForce GTX 2070'

3 : CPU = 'AMD Ryzen 5 2400G' | GPU = 'EVGA - GeForce GTX 2070'

How do we do this? Well we could just instantiate the object and add these configurations in the body of the script. This is certainly common, but i think it makes the script hard to read. It is always preferable to make the script read like a narrative. Alternatively, we can create a constructor that takes an argument, say an integer like "1", "2" or "3".

This seems cleaner to me and allows us to clean up our later code, while also creating discrete configurations that can be later appended or added to easily, because we are housing all our configs in one spot.

Lets create our class to build specific types of computers.

Good to see you are finally adding a GPU to this crappy build.

In my previous article I took the CPU name as the input to our constructor, this time all we are going to do is take a single integer. (i.e. 1,2 or 3)

So lets see how this is done.


Class PCSystem
{
    $CPU; $Mainboard; $Case; $PowerSupply; $RAM; $Storage; $GPU

First you can see we created our class with the declarations of what properties our class is going to house.


    PCSystem([int32]$Option)
    {
        [string]$this.Mainboard     = 'MSI B450M Mortar Titanium'
        [string]$this.Case          = 'Thermaltake Level 20 VT Chassis'
        [string]$this.PowerSupply   = 'SeaSonic FocusPlus Gold 650W'
        [string]$this.RAM           = 'Team Delta RGB - 16 GB DDR3000'
        [string]$this.Storage       = 'Samsung 970 EVO 500 GB'

Now we create our constructor. You can see we are taking the parameter '$Option' as our input to tell the constructor what to do. Now while we want to be able to change the CPU/GPU the rest don't change so rather than repeatedly declare the rest of the properties for each configuration - we are going to set the other properties now.


        switch($Option)
        {
            1{
                [string]$this.CPU  = 'AMD Ryzen 5 2400G'
                [string]$this.GPU  = ''
             }
            2{
                [string]$this.CPU  = 'AMD Ryzen 3 2400G'
                [string]$this.GPU  = 'EVGA - GeForce GTX 2070'  
             }
            3{
                [string]$this.CPU  = 'AMD Ryzen 5 2400G'
                [string]$this.GPU  = 'EVGA - GeForce GTX 2070'
             }
Default 
         {
                [string]$this.CPU  = 'Invalid configuration'
                [string]$this.GPU  = ''
             }
        }
    }
}

Lastly, we have done the most interesting bit, and using a switch statement we set the CPU/GPU properties based on which option the constructor is provided. (a bad input to $option will return the 'default' of "invalid configuration").

And there it is, we now have a way of creating this complex object in our script by simply calling it with an integer. Just to see what that looks like we might as well call option 3:


>_ [PCSystem]::new(3)

CPU          : AMD Ryzen 5 2400G
Mainboard    : MSI B450M Mortar Titanium
Case         : Thermaltake Level 20 VT Chassis
PowerSupply  : SeaSonic FocusPlus Gold 650W
RAM          : Team Delta RGB - 16 GB DDR3000
Storage      : Samsung 970 EVO 500 GB
GPU          : EVGA - GeForce GTX 2070

Can you think of other configurations this could apply too?

Why don’t you, I am tired from reading the millions of words

This configuration builder approach is a great way of dealing with building PowerShell objects. Importantly it also takes this configuration step out of your main logic, "separating the concern". For many dev's this is a pretty standard approach but for the System Engineer this may be a brand-new way of thinking about things. If you asking yourself, why should I do this, maybe hang in there for the next post when i wrap this up, but just offhand I have found this is great for structuring your scripts into discrete sections, it cleans up your configuration while putting it all in one place which any engineer could find. We have now a clear understanding of what each object needs, because the totality of it is defined at the start of the class and if we want to add a configuration we are using composition to include new configurations in the constructor which will then filter down through the whole script. Just some of the objects for which I have used this configuration class include: Virtual Machines, Network Adapter, and AD User/Computer configurations.

In the final part of this 3 part series, I will look at how to use this configuration object in a Function providing a full implementation and, you know - actually doing something with this class object that I have spent so long demonstrating.

If you can think of another type of configuration you could use this for, leave it in the comments below because I am always looking for new ideas.

Cheers,

The Infra Dev

To get updates on my new articles, follow me on Twitter @theinfradev

Photo by Philipp Katzenberger on Unsplash

Powershell: Keeping it Classy and Functional - Part 1of3

TheInfraDev — Mon, 21 Jan 2019 14:32:26 +0000

Let’s keep it Classy

"48 hrs to... Oh, Shutup!"

In PowerShell 5.0 Microsoft introduced proper Classes giving us a very powerful capability that to the average system admin probably went unused.
In fact, the greatness of classes is in how we can combine their data and functional capabilities with our standard PowerShell functions to create much cleaner code, with well-defined configurations and output.

If you have never created a Class in PowerShell or... ever, I suggest trying it out seperately. I won’t go into all the specifics as this is less about how to create a class, and more about what we can do with them, once we are comfortable. I suggest this guy’s blog as a good primer, or at least to bookmark for later.
Powershell Classes and Concepts

In this first post I will create our first data classes by emulating a physical process. In this case we are going to build a configuration for a little Gaming PC to hook up to the TV. The main build is not particularly powerful using only an AMD integrated GPU however it should be able to get decent performance for couch games such as Rocket League on medium settings at 1080p. Because of our use of classes we can later extend this configuration to make it (our PC configuration) more powerful.

Let’s create our first class to store our configuration

Can’t we just buy an Xbox or PS4? Seems easier.

Ok, so let’s define the parts we want in our little TV gaming box. We will need the following as our base config:

Mainboard: MSI B450M Mortar Titanium ($105)
RAM: Team Delta RGB - 16 GB DDR3000 ($135)
Storage: Samsung 970 EVO 500 GB ($128)
Case: Thermaltake Level 20 VT Chassis ($105)
PSU: SeaSonic FocusPlus Gold 650W ($90)

We are going to standardize around this platform allowing use to make slight changes to CPU, GPU if we want to beef up the processing power.

I don’t particularly want to go into the reasons why I have chosen AMD over INTEL or 16GB over 8GB but suffice to say If you build this computer it should all work.

So how do we do this as a class in Powershell. Well the first thing to know is PowerShell makes this super easy and we can essentially just list our items and PowerShell will worry about how to construct the object. This is the simplest way we can create our configuration.

Class PCSystem
{
   [string]$CPU
   [string]$Mainboard   = 'MSI B450M Mortar Titanium'
   [string]$Case        = 'Thermaltake Level 20 VT Chassis'
   [string]$PowerSupply = 'SeaSonic FocusPlus Gold 650W'
   [string]$RAM         = 'Team Delta RGB - 16 GB DDR3000'
   [string]$Storage     = 'Samsung 970 EVO 500 GB'
   [string]$GPU
}

In the above example we can see that we have declared the variable type and then the variable name. For some that is all we have declared, however for others we have declared a default value. This means when this object is instantiated later, we already have these values keyed in. Because I want to keep our options open I have kept our CPU/GPU options as undeclared values.

Now we have this base class we can instantiate it.

$TVPC =  [PCSystem]::new()

Now I am going to add a little gem of a Processer, an APU (CPU + GPU) from AMD that will give our box some great processing capacity and due to the integrated GPU gives us a low end gaming system for very little money. (USD$158)

$TVPC.CPU = 'AMD Ryzen 5 2400G'

Now our CPU is added, we have our base system. If we print this to console we get:

CPU         : AMD Ryzen 5 2400G
Mainboard   : MSI B450M Mortar Titanium
Case        : Thermaltake Level 20 VT Chassis
PowerSupply : SeaSonic FocusPlus Gold 650W 
RAM         : Team Delta RGB - 16 GB DDR3000 
Storage     : Samsung 970 EVO 500 GB 
GPU         :

Perfect, now we have a simple object which describes our configuration which we can pass around between functions as we like. Later if we decide we need extra storage or any other attributes we can just add them to our class, and they will automatically be instantiated, so we have a very extensible config.

Let’s make our own Class constructors!

I thought we were going to let PowerShell do that for us?

You are probably thinking, that’s kind of cool, Job done! Well, yes it is. But we can do it better.

The great thing about classes is that unlike say a hash table - we can add behaviour(methods) to a class via a constructor.

Quick primer: A constructor tells the language engine how to build the Class object.

We can give the class logic so that if the class is not provided input on creation - it will be the default class, or alternatively create a more custom version of the class if provided a configuration option.

Let’s have a look at what the constructor looks like. (I am going to compress the variable declarations at the top because it looks neater).

Class PCSystem
{
   $CPU; $Mainboard; $Case; $PowerSupply; $RAM; $Storage; $GPU
   PCSystem([string]$CPU)
   {
       [string]$this.CPU           = $CPU 
       [string]$this.Mainboard     = 'MSI B450M Mortar Titanium' 
       [string]$this.Case          = 'Thermaltake Level 20 VT Chassis'
       [string]$this.PowerSupply   = 'SeaSonic FocusPlus Gold 650W'
       [string]$this.RAM           = 'Team Delta RGB - 16 GB DDR3000'
       [string]$this.Storage       = 'Samsung 970 EVO 500 GB'
    }
}

So what is the difference here? Well, now we have made a constructor method that has the same name as the class (this is important). PowerShell will now treat this method as its constructor and knows that when an instance of this object is created it must follow the rules provided in this method:

First, instead of declaring the defaults when we create the variables we are doing it in the constructor, this allows us to make this decision depending on the constructor rather than just by default.
Second, we are requiring that on creation, a value be given for the CPU. This way we are requiring the decision early, but ultimately saying - without this we cannot proceed.
Third, in this particular case you will note the GPU is ignored. This particular configuration doesn’t care about GPU so we don’t need to specify it. However the GPU attribute will still be created because it is referenced at the top of the class.
Note: Like many other languages when you refer to a variable of the class, (like CPU for example) we need to call it "$This.CPU". The ‘this’ part of the parameter is the way .NET handles talking about the actual instances of the object rather than the abstract class we are working from here. In our example earlier where we created the $TVPC object, "$this.CPU" is an analogy for writing "$TVPC.CPU".

Due to this constructor, we can now define our CPU on creating the variable, shrinking our code from 2 lines to 1 and making sure the object is at a minimum spec from the beginning.

We can now create it, like so:
```
$TVPC =  [PCSystem]::new('AMD Ryzen 5 2400G')
```
What’s Next?

Wait, you were saying stuff? Sorry I was busy downloading Red Dead Redemption 2 on my PS4 that I just bought.

I hope that while I am using a real world physical object here, you could see how this could be used to describe configuration of any complex function. And by using a simple constructor we could create minor variations of our configuration which we can call depending on circumstance. Say for example, you want to create a fleet of VMs and you have 2 different memory configurations. By having these constructors you can save a lot of time and duplicated code by just changing the input to the constructor from one config to the other, and PowerShell will take care of the rest.

OK, that is it for this post, In my next post I will look at how we can use constructors further as well as general class methods to build a script into a more complex yet maintainable bit of software.

Cheers,

TheInfraDev

To get updates on my new articles, follow me on Twitter @theinfradev

Photo by Heng Films on Unsplash

How To Not Write A Blog Post

TheInfraDev — Sun, 23 Dec 2018 10:48:27 +0000

Thoughts on writing a blog

My phone buzzes, it is an alarm that goes off every 2 weeks on a Friday.

"You have 48 hrs to write a blog post."

It is meant to be a motivating reminder, yet it is received more like a kidnapper’s ransom demand. A forceful reminder that it is time to get two weeks of random thoughts compressed onto the page, ready for review by my beautiful wife (to make sure I didn’t make any horrendous errors, like using there instead of their, or trying to figure out if it is accept or except). Ready for publishing to the world, ready for the glare of the dazzling lights of my own hubris, by next Wednesday* at the latest.

I open my standard blog template, with markdown ready to go.

...The cursor blinks forlornly. A call to action if I ever did see one.

"You brought this on yourself", I mutter under my breath.

I have a headline idea but there are all these stupid questions in my way...

I thought this was a blog about writing shitty scripts? I think you have a bad case of "Gone Meta"

It goes something like this.

For my next blog I have a grand idea, how to use classes in PowerShell to aid the building of a great script. But I don’t like extremely long blog posts. I want to keep it at about 600-1000 words. And with that in mind, how do you condense everything that is great about encapsulation and composition and polymorphism to that size - to an audience that may or may not know what those things are? How do you NOT start at the beginning? I don’t want to start at the beginning, better developers than I have done that, and I should only refer to their esteemed work rather than stumble over it badly.

But in the meantime I do have something important to say about classes, about POPO’s (Plain Old PowerShell Objects. Get it? Well if you aren't a dev - probably not. haha... ahem.). There’s the stuff about using classes to hide your implementation of methods and lastly how you can then use those building blocks to make really cool functions that work 95% of the time, every time. Shit, how do you explain interfaces...?

I am only like 5 blog posts in, the first couple were more "about the mission" a.k.a. why I want to do this. Whereas this stuff, this is the good stuff. This is what people actually want to learn and this is what I have to give. And yet, can the 6th post instead be a meta description of blogging? Does everyone feel like this? Do all the people who - with good intention - set out to write a little about what they know and love, stumble upon this road where the possibilities are infinite, the likelihood of sounding like a gibbering mess is high and... really, please forgive me, I meant well... Oh dear.

Let’s take a step back

For that, do you not have to take a step forward first?

The cursor blinks forlornly. I look up, I have an idea. I’ll make it a three-part series. Yeah, that’s it. The first part is about creating simple classes to pass around data, then the methods, finally I’ll wrap it all in a nice function. Brilliant, pat on the back. Now, what will I use as my example? ... ah nuts... The cursor blinks forlornly. How does it do that? How can a cursor be forlorn?

Bastard.

Let me leave you with something useful!

It’s really the least you can do after this rambling mess

As the Holiday season is basically now and (you might have guessed) I have postponed the first of the all! Important! Three! Part! Series! till January, let me leave you with a gift. Something that I have can write by heart now. How to write a simple but effective logging function in PowerShell. This will always be a good idea to implement near the start of your fun little scripts, I promise.

First declare an environmental variable at the start of your script with the log location like so:

$env:Logfile = "$AppPath\logs\$(get-date -format 'dd-MM-yyyy') - Application log"
#The get-date temporary variable here will make sure to add the date to the file name so you don’t end up with one giant 100MB log.

Then we will write the function itself.

Function Write-Log
{

Param([string]$LogEntry,[string]$Logpath,[string]$Color)
# We define our inputs #

$DateTime = Get-Date -format 'dd/MM/yyyy HH:mm:ss' ; if ($Color -notmatch "\w"){$Color = 'Gray'}

# Then we get the current date/time, and make sure we have a color choice (Gray as a default) #

$log = "$env:Computername : $DateTime : $LogEntry"

# Now we create our full log entry #

Out-File -InputObject $log -FilePath $LogPath -Append -NoClobber

# This is how we write it to a file #

Write-host $Log -ForegroundColor $Color

Finally we write it to the console so we can debug as we write the app.

}

So what have we created? Well if we run the function like so:

Write-Log -LogEntry "I wrote a nice log file" -Logpath $env:Logfile -color 'blue'

We will likely now have a new log at the desired location and a nice message on the console in blue like this:

Computer01 : 19/12/2018 06:48:02 : I wrote a nice log file

I hope this helps, and if you use it - that you enjoy having nicely formatted logs! Have a Merry Christmas and/or Happy Holidays.
See you next year for my amazing three-part series on PowerShell Classes and Functions and why they are so awesome together...

The InfraDev

To get updates on my new articles, follow me on Twitter @theinfradev

How to write great PowerShell functions!

TheInfraDev — Wed, 12 Dec 2018 12:08:32 +0000

So far I have talked about the InfraDev's mission, and what languages and tools you might use, so now I think it is time to look at some concrete examples of how people commonly write PowerShell functions, and then how to improve them to be more stable, readable, and maintainable while living up to the standards of the Powershell community. One of the key skills in an InfraDev’s life, is the ability to write functions. Functions allow us to:

Re-use and share code by making standard implementations.
Encapsulate and therefore hide our implementation (not for security, but readability).
Make clear Entry and Exit points to different behaviours.
Change a swiss army knife into a hammer

Let's start with a common way people write functions

I have heard it is good to start at the beginning

I have chosen a rather simple and common form of a function. We are going to provide config data (Computername) and then return services data narrowed down to just the Name and Status properties.

$GLOBAL:ComputerName = 'Server01'
Function Get-ServiceData

{
Get-Service -ComputerName $ComputerName | Select-Object -Properties Name,Status
}

Get-ServiceData

So what are the key features of this Function?

$Computername is out of scope and so is declared as a Global variable. This is a very fragile and just all-round bad practice. Bad Coder! Bad!
The data we are returning is instead printed to the console (sometimes called Stdout). This is bad for the purposes of extending the use of the function. In fact our function is not returning any data.
If get-service fails for any reason - we get an error, but nothing returns to our console (std out). Worse, because we were using write-host, we have no way of checking what happened! This is not good if we ever want to use this as a chain of functions or check programmatically whether the function succeeded or failed.

Things you might not know: "What is StdIn / StdOut?" (Linux information project definition) Standard output, sometimes abbreviated stdout, refers to the standardized streams of data that are produced by command line programs (i.e., all-text mode programs) in Linux and other Unix-like operating systems. These standardized streams, which consist of plain text, make it very easy for the output from such programs to be sent to a devices (e.g., display monitors or printers) or to be further processed by other programs." more...

Let's make this function better

It's time to get technical?

$ComputerName = 'Server01'
Function Get-ServiceData ($ComputerName)

{
$Service = Get-Service -ComputerName $Computername
Return $Service

}
$RemoteServices = Get-ServiceData -ComputerName $ComputerName

$ComputerName is in scope as we are passing it into this function as a parameter. This not only stops the global variable issue, but also means that other people using this function don’t have to magically know that they must declare this variable first.
The Get-Service data is now added to a variable and is properly returned as output of this function. This provides for re-use of the output.
Further, we are also capturing the Return of our function in the $RemoteServices variable which we can then either evaluate and use further or just write to the console.
We haven’t fixed all the flaws, because If Get-Service fails for any reason - we still return nothing and anything relying on the return of this function is out of luck.

Is this best implementation? No, this is still a fragile implementation, but we have resolved some issues around returning the data and passing in data

Let's go all the way to stable, maintainable code

This won’t be javascript then j/k ;)

$ComputerName = 'Server01'
$RemoteServices = "No data"

Function Get-ServiceData

{
[CmdletBinding(SupportsShouldProcess)] Param([string]$ComputerName)
$Service = "Unable to retrieve data"

$Service = Get-Service -ComputerName $Computername

Return $Service

}

$RemoteServices = Get-ServiceData -ComputerName $ComputerName

$Computername is in scope as we are passing it as a parameter into this function.
We have also given ourselves extra PowerShell cmdlts such as -whatif and -confirm through using the [CmdletBinding(SupportsShouldProcess)] syntax. Rather than the () we used before, now we are using best practice and changing our function into a proper 1st class PowerShell cmdlet.
We declared that the input data is a string. This provides a type check to make sure we are giving the right type of variable and if not, it will cast it as a string anyway. While the function may fail to provide us the data we want, it will provide data.
Get-Service data is added to a variable that is already initialised. If Get-Service fails to retrieve any data, our original data will be kept. If it succeeds our data will be overwritten by the object returned.
If Get-Service fails for any reason - we get an error message.
Finally $RemoteServices is also initialised as a string 'No data' which is no longer a null or undefined variable. This also means if Get-Service fails we will then have our error declared and ready to be returned. Therefore, we know that if we get this back as the return, the Get-Service cmdlet failed.

Let’s wrap this up

Finally, some good news!

Each of these implementations would have worked and without rigorous testing we might have even considered them working functions. Up until they didn't, and the wrong data was fed in, or the wrong data came back. What I have tried to show here is how we can use a couple of key principles to provide stability to our functions.

Yes, the function is longer, and yes we have also nailed down a few concrete details such as variable types which is perhaps not in the dynamic nature of PowerShell - but by doing this we have made this function safer in the overall context and we have also made sure our hypothetical tool wouldn't error out due to nulls or failures in the implementation itself. Instead when we get bad data, we can recognise and refactor to compensate.

In further posts I will go into how to apply the same techniques in different styles of functions and start working with classes and objects. For now I hope the takeaway is that with a few changes to writing style we can create more stable code, that still provides the same data in an easy to read format.