DEV Community: Brandon Olin [1x Engineer]

9 Tips for Writing Better PowerShell Functions

Brandon Olin [1x Engineer] — Sat, 07 Dec 2019 00:00:00 +0000

One of the most common tasks in PowerShell is writing PowerShell functions. Functions are one of the basic building blocks we use to separate and abstract our code away. Without them, our scripts would be just a tangled mess of if statements, while and for loops, and duplicated code.

Functions allow us to package our PowerShell logic into discreet blocks we can call, pass parameters to affect how they work, and reuse them so we can follow DRY (Don't Repeat Yourself) principals.

PowerShell has a lot of functionality tucked away into functions that sometimes are not known, ignored, or forgotten about entirely. Let's talk about some basic things we can add to functions that improve our scripts and ultimately make us better tool makers.

Tip 1: Functions Should Do One Thing
Tip 2: Functions Should Be Testable
Tip 3: Functions Should Be Self-Contained
Tip 4: Add Comment-Based Help
Tip 5: Use The PowerShell Function Naming Convention
Tip 6: Leverage Advanced Functions
Tip 7: Support the Pipeline
Tip 8: Support -WhatIf If Making Changes
Tip 9: Support -Confirm if Making Changes

Tip #1: Functions Should Do One Thing

First off, let's make one thing clear. Functions should do one thing and one thing only.

Give me a ping Vasili, one ping only please.

- Capt. Marko Ramius - The Hunt for Red October

I've seen countless PowerShell functions that try to cram in entirely too much logic and end up being an unwieldy mess. These large, unfocused functions end up being hard to understand as they have no clear purpose. They can perform in strange ways, utterly unrelated at all to what the user thinks the function does.

I'll admit, I do this myself sometimes (hey nobody's perfect). This is especially true when you're writing code for the first time to perform a new task. It's easy to fall into the trap of handling this one edge case here, this other edge case there, maybe output this variable if these set of conditions are true, etc.

We must recognize when this happens, and to correct the situation as soon as possible. If we don't, we'll end up struggling to support an unmaintainable function, our productivity suffers, and the users of our code become frustrated at the lack of focus.

Tip #2: Functions Should Be Testable

In short, single-purpose PowerShell functions are easier to write tests for in tools like Pester. We can create tests for the (hopefully one or just a few) different scenarios of expected input parameters and validate the function produced the expected output. If the function does too many things, writing unit tests becomes difficult or almost impossible.

It's better to have a handful of small, discreet functions with quality unit tests than one large function with no or poor unit tests.

Tip #3: Functions Should Be Self-Contained

It's almost a certainty that your PowerShell function is working with variables in some way. A good practice is to supply the function with all the external variables it may need to perform its task as parameters into the function.

If our function only reads external variables, it's a good idea to add parameters to the function, with the default value being the external variable.

A big reason to do this is it helps make writing unit tests for functions easier.
We can confidently test a function in isolation, and verify the outputs if we supply all the required information directly into the function.

When functions access external variables and make assumptions on their contents, hard to troubleshoot bugs can occur if those variables had their contents modified but another function.

Tip #4: Add Comment-Based Help

PowerShell has this excellent feature called comment-based help. Use it to provide users of your code clear guidance on what it does and how to use it.

When PowerShell parses your function, the comment-based help contained within is accessible via the builtin Get-Help cmdlet. The help text for a function doesn't need to be a novel, but clear and accurate help on what the function does, descriptions for each parameter, and useful examples for how to use the function is one of the best ways to delight the users of your function. Conversely, having no or inaccurate help is one of the easiest ways to frustrate the users of your software with the genuine possibility of them stopping to use it at all.

Tip #5: Use The PowerShell Function Naming Convention

PowerShell uses a Verb-Noun syntax for functions and cmdlets. You can see the list of approved verbs with descriptions about what they are intended for by running the Get-Verb command.

A big reason for the approved verb list is consistency. The creators of PowerShell wanted it to provide a consistent experience to the user. This consistently also enhances PowerShell's readability.

If a function is called Get-IpAddress, there is little ambiguity as to that the function does. It returns an IP address. It does not set the IP address or otherwise make changes to the system.

If we wanted to set the IP address, it would be intuitive to have a Set-IpAddress function.

I've seen many custom PowerShell functions use the Get verb but internally make non-obvious changes to the system. This not only causes confusion because you're wondering: "Hey! I just got my IP address. Why did my recycle bin get cleared out?" It also has the potential to cause harm, as the actions of the function does not match what the user expects.

This is a big no-no in PowerShell.

Tip #6: Leverage Advanced Functions

PowerShell gives you a excellent set of features you can use in functions for practically free if you make them advanced functions. By adding the [CmdletBinding()] attribute to a function, you now have access to a set of common parameters you can utilize for things like:

Writing verbose messages
Supporting -Confirm and -WhatIf modes
Parameter validation
Support input from the pipeline
Advanced parameters

When creating new functions, it is a good practice to make them advanced functions as a matter of course. This allows you to support the features above easily should you need them.

Tip #7: Support the Pipeline

This is an extension of Tip #6, but I feel it deserves its own section. If you're adhering to Tip #1 and writing functions that do one thing only, then supporting the pipeline is an important feature to add so functions can be chained together to perform more complex logic.

Advanced functions add support for the ValueFromPipeline argument attached to parameters via the Parameter attribute.

Adding this argument indicates to PowerShell that the value of the parameter can come from a pipeline object. This allows you to stream the value of the parameter from the output of another function/cmdlet.

For more information about the PowerShell pipeline, check out the about_pipelines help doc or run Get-Help about_pipelines from PowerShell itself.

Tip #8: Support -WhatIf If Making Changes

PowerShell's support of the -WhatIf switch parameter is analogous to --dry-run or --noop in other tools. When specifying the -WhatIf switch, what you're essentially telling PowerShell is: "Tell me what you're going to do, but don't actually do it."

It's a great tool to have when running PowerShell interactively to validate a series of actions that could potentially have serious effects without actually making them.

Imagine you needed to run a command to delete files from a directory recursively. You want to delete all .log files from the C:\tmp directory but also want to be extra careful that you don't inadvertently delete other files, so you add the -WhatIf switch to Remove-Item like so:

Get-ChildItem -Path C:\tmp -File *.log -Recurse | Remove-Item -WhatIf

With this, you can see all the files that Remove-Item would have deleted if you hadn't provided the -WhatIf switch. After validating the files displayed, you safely remove the -WhatIf switch and rerun the command to remove the files.

-WhatIf is only supported in advanced functions, so it’s another reason to implement Tip #6. When authoring functions that affect the system in some way, add -WhatIf support via the SupportsShouldProcess argument on the [CmdletBinding()] attribute.

Check out Boe Prox's article about Adding -WhatIf Support to Functions and Scripts.

Tip #9: Support -Confirm if Making Changes

Related to Tip #8, the -Confirm switch indicates to PowerShell to pause before every action and display an interactive prompt asking you to confirm the action before it executes. It will do this for every object in the pipeline, allowing you to inspect the item before continuing.

Just like with -WhatIf support, adding -Confirm support is only possible with advanced functions, so Tip #6 still applies.

Check out vex32's excellent article about adding support for -Confirm to your functions.

Closing

One of the problems with making a list of tips is knowing when to stop. There are many more tips I could have added about writing functions or even a list of things to definitely not do. Those will have to wait for another day.

Cheers!

Icon courtesy of Tip Icon #388700

Infrastructure Testing with Pester and the Operation Validation Framework

Brandon Olin [1x Engineer] — Sat, 20 Jul 2019 04:41:42 +0000

If you've been using PowerShell for any length of time in the past few years, you have undoubtedly heard of Pester. If not, then you're probably living in a strange parallel universe where the Zune is still a thing. In any case, Pester is THE testing framework for PowerShell and is a must-have tool in your Infrastructure Developer toolbox.

I say Infrastructure Developer because that is what we are. If you write production code to automate your infrastructure, then you are not a Systems Engineer or Administrator, a SharePoint Engineer or anything else, you are a developer. Full stop.

The fact that we write PowerShell code that defines or runs IT infrastructure is not any different than a web developer using CSS, JavaScript, and HTML, or a full-stack ninja rockstar slinging micro-services written in Go on Kubernetes.

Everything involves working with code therefore everyone is a developer.

- Sun Tzu

Your traditional developer working with C# or Java tests their code. Your traditional Windows administrator using PowerShell to automate their jobs away (you won't) SHOULD test their code. Even if you're not writing tests in Pester, RSpec, SpecFlow, etc, you are testing your code. Or I should say, your users are testing your code for you.

What about your Infrastructure?

Do you test your infrastructure to verify it is working the way you expect? Are your services configured according to your specifications? Your infrastructure is not a static object; never changing and forever in the state you expect.

If you're not actively testing your infrastructure, don't worry, your users WILL let you know when it's not working :)

Things change. Always.

- Abraham Lincoln

Servers get provisioned or deprovisioned, new applications come online, or old ones fade away into the sunset. What about the gremlins chewing on the wires causing latency between services, or buggy code (cough...not yours of course) causing applications to crash? What about that outage last week where you manually tweaked a setting but forgot to backport it into your DSC configuration? All of these things create a living, breathing, dynamic environment. That environment must be tested to ensure your infrastructure reality matches your desired state.

This is where tools like Pester and the Operation Validation Framework can help.

Operation Validation?

You know what Pester is and know that you use it to test the functionality of your PowerShell scripts/modules. Did you know you can also use it to test your infrastructure? When you think about it, all Pester is doing at the end of the day is comparing a value on the left (your actual state), to a value on the right (your desired state) and raising an alarm when these don't match.

Get-Answer.ps1

function Get-Answer {
    param(
        [parameter(Mandatory)]
        [string]$Question
    )

    if ($Question -eq 'Answer to the Ultimate Question of Life, the Universe, and Everything') {
        42
    }
}

Get-Answer.tests.ps1

describe 'Get-Answer' {
    context 'Correct output' {
        it 'Returns the correct value' {
            Get-Answer -Question 'Answer to the Ultimate Question of Life, the Universe, and Everything' | Should -Be 42
        }
    }
}

The test above is validating the output of our Get-Answer function. Now take a look at an infrastructure test:

os.services.tests.ps1

describe 'Operating System' {
    context 'Service Availability' {
        it 'Eventlog is running' {
            $svc = Get-Service -Name Eventlog
            $svc.Status | Should -Be running
        }
    }
}

Looks similar to me 😊

Operation Validation Framework

Now that we know we can use Pester to test our infrastructure, what do we do with these tests and how do we execute them? What if we wanted to version these tests and publish them? Hey, that sounds like a PowerShell module!

Your ideas are intriguing to me and I wish to subscribe to your newsletter.

- Sir Isaac Newton

This is where the Operation Validation Framework comes into play. It is a PowerShell module that searches for Pester tests contained in a defined folder structure in your other PowerShell modules and ...wait for it... executes them with Pester. That's it. By just putting our Pester tests in a module, we can now version them, publish them, and execute them!

Folder Structure

The Operation Validation Framework, or just OVF, expects Pester tests inside a known location in your module. If you put Pester tests inside a Diagnostics\Simple or Diagnostics\Comprehensive folder under your module, OVF can find these and execute them. The Simple folder is intended for tests that are quick and non-intrusive to execute. These tests could be executed every few minutes with little impact. The Comprehensive tests would be for more involved and take longer to execute. You’d probably run these every few hours or once a day.

MyTestModule\
- MyTestModule.psd1
- Diagnostics\
- Simple\
  - services.tests.ps1
  - logicaldisks.tests.ps1
- Comprehensive\
  - performance.tests.ps1

As an example, let’s say we have a PowerShell module with the structure above. This module includes the Pester tests below. Notice that both Pester test scripts have parameters that define some default values. Pester has this nifty feature where you can invoke a test script and inject parameters into it. This allows you to provide some sane defaults for your tests yet allow the user to override them if they need to. OVF also supports this feature. This means that you can write generic OVF modules designed to test a certain product or OS feature and publish them to the PowerShell Gallery! Users can then download and execute these, overriding the default parameters if necessary to fit their environment. We’d have common infrastructure tests that the whole community could use!

Myself and others have already published a few OVF modules to the PowerShell Gallery. Check out these simple OVF modules to test Windows Server, Active Directory, SharePoint, and Citrix ShareFile.

services.tests.ps1

param(
    $Services = @(
        'DHCP', 'DNSCache','Eventlog', 'PlugPlay', 'RpcSs', 'lanmanserver',
        'LmHosts', 'Lanmanworkstation', 'MpsSvc', 'WinRM'
    )
)

describe 'Operating System' {
    context 'Service Availability' {
        $Services | ForEach-Object {
            it "[$_] should be running" {
                (Get-Service $_).Status | Should -Be running
            }
        }
    }
}

logicaldisk.tests.ps1

param(
    $FreeSystemDriveMBytesThreshold = 500,
    $FreeSystemDrivePctThreshold = .05,
    $FreeNonSystemDriveMBytesThreshold = 1000,
    $FreeNonSystemDrivePctThreshold = .05
)

describe 'Logical Disks' {

    $vols = Get-Volume | Where-Object { $_.DriveType -eq 'Fixed' -and -not [string]::IsNullOrEmpty($_.DriveLetter)}
    context 'Availablity' {
        $vols | ForEach-Object {
            it "Volume [$($_.DriveLetter)] is healthy" {
                $_.HealthStatus | Should -Be 'Healthy'
            }
        }
    }

    context 'Capacity' {
        $systemDriveLetter = $env:SystemDrive.Substring(0, 1)
        $sysVol = $vols | Where-Object DriveLetter -eq $systemDriveLetter
        $nonSysVols = $vols | Where-Object DriveLetter -ne $systemDriveLetter

        it "System drive [$systemDriveLetter] has $FreeSystemDriveMBytesThreshold MB and $('{0:p0}' -f $FreeSystemDrivePctThreshold) free" {
            ($sysVol.SizeRemaining / 1MB) -ge $FreeSystemDriveMBytesThreshold | Should -Be $true
            ($sysVol.SizeRemaining / $sysVol.Size) -ge $FreeSystemDriveThresholdPct | Should -Be $true
        }

        foreach ($volume in $nonSysVols) {
            $driveLetter = $volume.DriveLetter
            it "Non-System drive [$driveLetter] has greater than $FreeNonSystemDriveMBytesThreshold MB and $('{0:p0}' -f $FreeNonSystemDrivePctThreshold) free" {
                ($volume.SizeRemaining / 1MB) -ge $FreeNonSystemDriveThreshold | Should -Be $true
                ($volume.SizeRemaining / $volume.Size) -ge $FreeNonSystemDriveThresholdPct | Should -Be $true
            }
        }
    }
}

Always remember that you are absolutely unique. Just like everyone else.

- Mister Rogers

Now let’s see how to execute these same tests but using OVF. Since our test module has been installed into $env:PSModulePath, OVF will find it, inspect it, and return a collection of tests. These tests can then be executed with Invoke-OperationValidation. Imagine having your monitoring system running the simple script below and throwing alerts if any of the Pester tests have failed.

Import-Module OperationValidation
$tests = Get-OperationValidation -ModuleName MyTestModule
$results = $tests | Invoke-OperationValidation
$results

To execute the OVF tests and override the default parameters, we can use the -Overrides parameter. We can also show the Pester output as well. The cool thing about this framework is that you can develop a common module to test a certain technology and then tailor the settings per environment.

Wrapping Up

Using Pester to test your infrastructure should become a common practice for IT administrators. Everything is starting to be defined in code and like I said at the beginning, we are all developers now. We may be coding infrastructure, but the basics of software development still apply. Shouldn’t we be testing like a developer too?

Using PoshBot Middleware for Rate-Limiting Notifications in Slack

Brandon Olin [1x Engineer] — Mon, 15 Jul 2019 00:00:00 +0000

Recently, someone in the #ChatOps channel of the PowerShell Slack workspace asked if it’s possible to use PoshBot to send a message recommending people to use Slack threads if they send over (x) amount of messages in (y) amount of time. I suppose he wanted to encourage threaded conversations to reduce the clutter in his Slack workspace. Here’s the solution I sent him that I adapted from a Stack Overflow question about rate-limiting. What we’ll use to track user message rate is known as the token bucket algorithm.

PoshBot Middleware

PoshBot has the concept of middleware hooks, which is the ability to execute custom PowerShell scripts during certain events in the command processing lifecycle. These hooks can do pretty much anything you want. After all, they are just PowerShell scripts. If you follow the conventions outlined in the documentation, they are pretty straightforward to set up and can extend the utility of our ChatOps tooling.

Middleware Hook Stages

There are six different stages that middleware can execute. Middleware can modify the command received, the response back to the backend, or even to drop the message entirely and not allow it to execute. You pick the appropriate stage depending on what your middleware is doing.

Name	Description
PreReceive	Runs before PoshBot “receives” the message from the backend
PostReceive	Runs after the message is “received” from the backend, parsed, and matched with a registered bot command
PreExecute	Runs before a command is executed
PostExecute	Runs after a command has been executed but before responses are sent to the backend
PreResponse	Runs before responses are sent to the backend
PostResponse	Runs after responses have been sent to the backend

Adding the Middleware Hook

Middleware hooks are added to your bot configuration under the property called MiddlewareConfiguration. For the rate-limiting example I created, we’re going to use the PreReceive stage because this middleware is intended to count normal messages occurring in Slack, not necessary just bot commands. All the other stages run after a message has been parsed and matched to the bot command. If we used any other stage, we’d only be measuring the rate of bot commands, not normal Slack messages.

In your bot configuration .psd1 file, add the following to the MiddlewareConfiguration property. Adjust the hook name and path as desired.

@{
    #
    # Other sections omitted for brevity
    #
    MiddlewareConfiguration = @{
        PreReceive = @{
            Name = 'RateLimiter'
            Path = 'C:/Users/Brandon/.poshbot/middleware/rate_limiting_notice.ps1'
        }
        # PostReceive = @{
        # Name = ''
        # Path = ''
        # }
        # PreExecute = @{
        # Name = ''
        # Path = ''
        # }
        # PostExecute = @{
        # Name = ''
        # Path = ''
        # }
        # PreResponse = @{
        # Name = ''
        # Path = ''
        # }
        # PostResponse = @{
        # Name = ''
        # Path = ''
        # }
    }
}

Now let’s look at rate_limiting_notice.ps1 and go through each section.

rate_limiting_notice.ps1

The full script is found in this GitHub gist.

PoshBot middleware hooks are just standard PowerShell scripts, but PoshBot expects two parameters to be available and passes specific objects to them.

$Context is a PowerShell object containing a ton of information about the incoming message received from the backend. Who sent the message, what channel it was in, the raw JSON message from the backend, etc. Our middleware needs to accept this object as the first parameter to the script.

$Bot is the main PoshBot instance object. It is essentially a PowerShell class instance with a bunch of methods implementing all the bot logic. Our middleware is given access to this object so we can perform deep modification of PoshBot internals. Remember, with great power comes great responsibility.

<#
.SYNOPSIS
    Suggest Slack threads for talkative users.
.DESCRIPTION
    This middleware tracks how many messages (x) users send per (y) amount of time.
    If a user goes over the threshold, we'll send a message suggesting that Slack threads should be used.
.NOTES
    Based on https://stackoverflow.com/questions/667508/whats-a-good-rate-limiting-algorithm
#>
param(
    $Context,
    $Bot
)

This next section is where we’ll tell PoshBot to log a message that this middleware hook is starting and defining our rate-limiting values. We’ll also pull out the calling user ID from the context object. We define our rate-limiting window in seconds but to allow greater precision for the actual measurements, we’ll use milliseconds internally.

We also need to be sure we DON’T measure messages already in a threaded conversation, or to count other messages PoshBot receives about updates to threaded conversations. If we don’t exclude these, our rate-limiting won’t work correctly and we’ll pester people to use threaded conversations when they already are and that would be…awkward.

$Bot.LogDebug('Beginning message ratelimit middleware')

# We'll allow (5) messages per user in a (60) second window before suggesting threads
$maxMsgs = 5
$timePeriod = 60

$userId = $Context.Message.From
$timePeriodMS = $timePeriod * 1000

# Only measure messages NOT already in a thread
# This middleware hook stage also receives extra messages whenever a user replies in a thread
# We need to ensure we DON'T count these against the rate-limiting
$unThreadedMsg = (
    ([string]::IsNullOrWhiteSpace($Context.Message.RawMessage.thread_ts) -and
    ($Context.Message.RawMessage.type -eq 'message' -and $Context.Message.RawMessage.subtype -ne 'message_replied'))
)

Next, assuming we’re processing an unthreaded message, we’ll either load up a tracking object or create a new one if it doesn’t exist. We’re storing this data as a CLIXML file, so we need to use Import-Clixml to retrieve the object. This tracker is a hashtable with the user ID as the key, and a hashtable containing the user’s current message allowance and the last time they sent a message as the value.

if ($unThreadedMsg) {
    # Load the tracker
    $trackerPath = Join-Path $Bot.Configuration.ConfigurationDirectory 'msg_ratelimiting_tracking.clixml'
    if (Test-Path $trackerPath) {
        $tracker = Import-Clixml $trackerPath
    } else {
        $tracker = @{
            $userId = @{
                Allowance = $maxMsgs
                LastMsgTime = [datetime]::UtcNow
            }
        }
    }

Next, we’ll get the current time and determine how many milliseconds it’s been since the user last sent a message. This value is then used to calculate our bucket allowance.

$now = [datetime]::UtcNow
$timePassed = ($now - $tracker[$userId].LastMsgTime).TotalSeconds
$tracker[$userId].LastMsgTime = $now
$tracker[$userId].Allowance += $timePassed * ($maxMsgs / $timePeriodMS)

We now need to look at our allowance and determine if we’ve breached the rate limit set. If we have <1 allowance, then we send a friendly message back to Slack information the user that perhaps they should use Slack threads. We do this by creating a Response object, which is a class internal to PoshBot that represents a message we want to send to the backend chat network. We then reset the user’s allowance so we won’t keep on sending this message unless they breach the limit again. Lastly, we’ll save this data back to disk with Export-Clixml.

if ($tracker[$userId].Allowance -lt 1.0) {
    $Bot.LogDebug("User [$userId] has breached ratelimit of [$maxMsgs] messages in [$timePeriod)] seconds. Sending thread reminder response")
    $response = [Response]::new()
    $response.To = $Context.Message.To
    $response.MessageFrom = $Context.Message.From
    $response.OriginalMessage = $Context.Message
    $mentionUser = "<@$($Context.Message.From)>"
    $text = "Hey $mentionUser, we noticed you have a lot to say. Perhaps creating a Slack thread would be useful."
    $response.Data = New-PoshBotTextResponse -Text $text -AsCode
    $Bot.SendMessage($response)

    $Bot.LogDebug('Sending thread reminding response')

    # Reset so we don't send again until they breach the limit again
    $tracker[$userId].Allowance = $maxMsgs
} else {
    $tracker[$userId].Allowance -= 1.0
}

$tracker | Export-Clixml -Path $trackerPath

Finally, we’ll close out the if/else statement from above and log a debug message if we didn’t need to measure this message at all. We’ll then return the command context to PoshBot. Returning the $Context object to PoshBot tells it to continue with executing any other middleware hooks. If we wanted to tell PoshBot to stop processing this message, we return nothing from the script.

} else {
    $Bot.LogDebug("Ignoring message. It's already in a threaded conversation.")
}

# Return context back for any subsequent middleware
$Bot.LogDebug('Ending message ratelimit middleware')
$Context

Summary

The full script is found in this GitHub gist.

I hope this post was informative and highlighted the power and flexibility you have with PoshBot middleware hooks. I’m sure this script didn’t account for some edge cases and may even contain a bug or two, but I’ll leave that as an exercise for the reader.

Cheers

Joining Paths in PowerShell

Brandon Olin [1x Engineer] — Mon, 07 Jan 2019 00:00:00 +0000

Frequently in PowerShell, you’ll be dealing with file paths and programmatically constructing them to either write or read files. There are a few different ways to build up file paths in PowerShell which I’ll go over below.

Using a hard-coded string

It is very common to see file paths being created by specifying the exact, hard-coded path.

$path = 'C:\mypath\to\foo.txt'

This is problematic for a few reasons though. You’ll notice that we’re using c:\ in the string. This immediately limits the use of this to Windows as the concept of the C: drive only exists there.

In case you haven’t heard, PowerShell is cross-platform now with version 6. We need to start thinking about how our scripts will run if they are executed on macOS or Linux. Assuming that they will only ever be executed on Windows will limit their usefulness, especially if we ever intend to publish it for others.

The other issue with this example is the use of backslashes \. This may be the primary way to separate paths on Windows, but on Unix-like operating systems, the forward slash / is used. In most cases, PowerShell will normalize this for you on whatever OS you’re running on, and it is often forgotten that Windows also supports the forward slash / as a path separator, but this may not work in every scenario. To help ensure our scripts work in all environments, it is a good practice to use / if manually constructing a folder or file path.

Also, if you need to access a path like C:\mypath\to\foo.txt on Windows or similar on macOS/Linux, it would be better to use a mix of environment and/or built-in PowerShell variables to make it more resilient. In PowerShell 6, the new boolean variables $IsWindows, $IsLinux, and $IsMacOS will tell you what operating system you’re on, and on Windows, we can rely on $env:SYSTEMDRIVE to return the system drive. This is usually C:\ but in rare cases, could be another drive letter. On a Unix-like OS, we can use root /. We can use these variables to determine the correct path to use depending on the operating system.

if ($IsWindows) {
    $path = "$env:SYSTEMDRIVE/mypath/to/foo.txt"
} else {
    $path = '/mypath/to/foo.txt'
}

Using Join-Path

PowerShell includes the cmdlet Join-Path for taking multiple paths and returning a single path. This is a better method as Join-Path will ensure the correct path separator is used depending on the context.

The example below will return C:\foo on Windows.

$path = Join-Path -Path $env:SYSTEMDRIVE -ChildPath 'foo'

Joining three or more paths

Often, we’ll run into situations where we need to join more than two paths together. We could do something like:

$path = "$path1/$path2/$path3"

$path = Join-Path -Path $path1 -ChildPath "$path2/$path3"

or even worse:

$path = Join-Path -Path $path1 -ChildPath (Join-Path -Path $path2 -ChildPath $path3)

None of these are particularly elegant though.

Starting in PowerShell 6, Join-Path has a new parameter called -AdditionalChildPaths. This parameter takes a string array that you can use to include as many additional path sections as you need. With this, we can utilize the built-in cmdlet and not rely on any manual string concatenation.

$path = Join-Path -Path $path1 -ChildPath $path2 -AdditionalChildPaths ($path3, $path4)

These parameters also work positionally so you can skip specifying the parameters names if you desire. This technically goes against established PowerShell style guidelines for explicitly using parameter names but for common cmdlets, it is generally accepted.

$path = Join-Path $path1 $path2 $path3 $path4

Dipping into .NET

One of the great things about PowerShell is the ability to dip into .Net when you need extra power or flexibility. My new favorite method of constructing file paths is using .NET’s [System.IO.Path] class and the Combine() method. This method accepts two or more strings which it will combine in one operation and not rely on any manual string concatenation.

The great thing about this method is it works similar to PowerShell v6’s Join-Path and the -AdditionalChildPaths parameter, but works on lower versions of PowerShell as well, making your script or module even more portable.

$path = [IO.Path]::Combine($path1, $path2, $path3, $path4)

Happy ~~trails~~ paths :)

Using a Powershell Azure Function to Send Automated Blog Post Tweets

Brandon Olin [1x Engineer] — Fri, 07 Dec 2018 00:00:00 +0000

If you follow me on Twitter, you would have probably noticed that I occasionally send out tweets from random previous blog posts. I don’t want to have to remember to send these manually, and after reading how Josh King does it in his automated blog archive tweets article, I thought I’d add my spin on it. For my implementation, I’m going to use an Azure Function as well as a bit of blob storage to keep track of previous tweets. This way, I don’t depend on my local computer being up, and I can keep track of what posts I’ve already tweeted out, so I don’t repeat them. An example of one of these automated tweets is below:

All the code for this process can be found in the GitHub repo.

// Detect dark theme var iframe = document.getElementById('tweet-1065853467795775488-344'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1065853467795775488&theme=dark" }

TL;DR

This blog post tweeter works by consuming a JSON feed of previous blog posts, selecting one at random, generates a Bitly link to the post, then sends the tweet. A record of this tweet is then stored in Azure Storage, so subsequent invocations of the Function don’t re-send the same post until all available posts have been tweeted out. Once all available posts have been tweeted, the tracker is reset. For all the details about how this process works keep reading.

Blog Post JSON feed

I use the static site generator Jekyll for my blog and create a JSON file containing all previous blog posts any time I update the blog with new content. This JSON file can be found at https://devblackops.io/feed.json, and you can see how I generate it here.

A snippet of what this JSON looks like is below:

{
    "title": "DevBlackOps",
    "description": "Thoughts about DevOps and automation from a Windows guy",
    "url": "https://devblackops.io/",
    "date": "Fri, 07 Sep 2018 04:02:33 +0000",
    "posts": [
        {
            "title": "The PowerShell Conference Book",
            "url": "https://devblackops.io/the-powershell-conference-book/",
            "date": "Mon, 09 Jul 2018 00:00:00 +0000",
            "tags": [
                "PowerShell"
            ],
            "categories": [
                "PowerShell"
            ]
        },
        {
            "title": "The Operation Validation Framework: Test your infrastructure using Pester",
            "url": "https://devblackops.io/the-operation-validation-framework-test-your-infrastructure-using-pester/",
            "date": "Mon, 25 Jun 2018 00:00:00 +0000",
            "tags": [
                "PowerShell",
                "Infrastructure",
                "Testing",
                "Pester",
                "OVF",
                "Operation Validation"
            ],
            "categories": [
                "PowerShell"
            ]
        }
    ]
}

The Azure Function

This PowerShell-based Azure Function consumes the JSON feed from my blog, select a random post, then tweet it out. Hashtags are also created based on any tags defined in the blog post. I’m also borrowing some code from MeshkDevs in the InvokeTwitterAPIs repository to send tweets using PowerShell.

The Azure Function runs on a schedule and consumes the JSON feed from my blog. When the Function is triggered based on the schedule, a JSON-based tracker file hosted in Azure storage is passed as input. An array of available posts to tweet is created by taking the posts from the JSON feed and removing any previously tweeted posts contained in the tracker file. A random post is selected from whatever posts are left. This post is then tweeted out and added to the tracker file so it won’t be sent again until all available posts of been tweeted out.

The relevant bits of the Function are below. To see the whole function including how to create short links using Bitly and send tweets to Twitter, check out the whole file in the GitHub repo.

run.ps1

# I don't want these URLs tweeted out as they're not very relevant
$excludedPosts = @()

# Load tracker file
$tracker = Get-Content $inBlob | ConvertFrom-Json
Write-Output "Last tweeted: $($tracker.lastTweetedTime)"

# Get random blog post from feed
$blog = Invoke-RestMethod -Uri $env:BLOG_FEED_URL
$candidatePosts = $blog.posts.Where({$_.url -notin $excludedPosts})

# Get a post from the list of available posts that we haven't already tweeted
$tweetedUrls = $tracker.tweetedPosts | Select-Object -ExpandProperty url
$availablePosts = $candidatePosts.Where({$_.url -notin $tweetedUrls})
$post = $availablePosts | Get-Random
$availablePosts = $availablePosts.Where({$_.url -ne $post.Url})

if (-not $post) {
    # We've exhausted all available posts so reset
    # the tracker and get a new post from the candidates
    $post = $candidatePosts | Get-Random
    $tracker.tweetedPosts = @()
    $availablePosts = $candidatePosts.Where({$_.url -ne $post.Url})
}

$tracker.candidatePostsCount = $candidatePosts.Count
$tracker.availablePostsCount = $availablePosts.Count

if ($post) {
    $postJson = $post | ConvertTo-Json
    Write-Output "Retrieved post:`n$postJson"

    # Create hashtags
    $hashtags = ''
    $post.tags | Foreach-Object {
        $tag = $_ -replace ' ', ''
        $hashtags += (' #' + $tag)
    }
    $hashtags = $hashtags.Trim()

    # Create tweet text
    $title = $post.title
    $link = Get-ShortUrl -Url $post.url -OAuthToken $env:BITLY_OAUTH_TOKEN
    $tweetText = "From the blog archive: $Title`n`n$link`n`n$hashtags"
    Write-Output "Sending tweet:`n$tweetText"
    $oAuth = @{
        ApiKey = $env:TWITTER_CONSUMER_KEY
        ApiSecret = $env:TWITTER_CONSUMER_SECRET
        AccessToken = $env:TWITTER_ACCESS_TOKEN
        AccessTokenSecret = $env:TWITTER_ACCESS_SECRET
    }
    $tweetParams = @{
        ResourceURL = 'statuses/update.json'
        RestVerb = 'POST'
        Parameters = @{
            status = $tweetText
        }
        OAuthSettings = $oAuth
    }
    $tweet = Invoke-TwitterRestMethod @tweetParams
    $tweetJson = $tweet | ConvertTo-Json
    Write-Output "Tweet sent:`n$tweetJson"

    # Add tweeted post to tracker
    $now = (Get-Date).ToUniversalTime().ToString('u')
    $tracker.lastTweetedTime = $now
    $tweetedPost = @{
        url = $post.Url
        lastTweeted = $now
    }
    $tracker.lastTweetedPost = $tweetedPost
    $tracker.tweetedPosts += $tweetedPost
    $tracker.tweetedPostCount = $tracker.tweetedPosts.Count
    $tracker.candidatePostsCount = $candidatePosts.Count
    $tracker.availablePostsCount = $availablePosts.Count
    $trackerJson = $tracker | ConvertTo-Json
    Write-Output "Saving tracker to blob:`n$trackerJson"
    $trackerJson | Out-File -Encoding UTF8 -FilePath $outBlob
}

The Function bindings are defined in function.json. You can see that I’ve set a timer-based trigger to fire this function. You can check out how cron expressions work in the Microsoft documentation. In this example, the function is triggered every Monday, Wednesday, and Friday at 6:24am UTC.

I’m also defining an input binding to the tracker file contained in Azure storage. This same file is also defined as an output binding as the Function both reads and writes to it.

function.json

{
    "bindings": [
        {
            "type": "timerTrigger",
            "name": "myTimer",
            "schedule": "0 24 6 * * 1,3,5",
            "direction": "in"
        },
        {
            "type": "blob",
            "name": "inBlob",
            "path": "sendblogtwitter/posts.json",
            "connection": "blogarchivetweeter_STORAGE",
            "direction": "in"
        },
        {
            "type": "blob",
            "name": "outBlob",
            "path": "sendblogtwitter/posts.json",
            "connection": "blogarchivetweeter_STORAGE",
            "direction": "out"
        }
    ],
    "disabled": false
}

Deploying the Function

If you want to follow along at home, it is best if you clone the GitHub repo and cd into it to run the deployment commands

git clone https://github.com/devblackops/blog-archive-tweeter-example
cd ./blog-archive-tweeter-example

To start, we’re going to define all our variables up front. Fill in these with your relevant information. For generating Twitter tokens used by this process, you can start here. To generate a Bitly OAuth token, follow the directions here.

# Settings
$subscription = '<YOUR-AZURE-SUBSCRIPTION>'
$resourceGroup = '<RESOURCE-GROUP-NAME>'
$region = '<AZURE-REGION>'
$storageAcct = '<STORAGE-ACCOUNT-NAME>'
$storageContainerName = '<STORAGE-CONTAINER-NAME>'
$functionApp = '<FUNCTION-APP-NAME>'
$blogFeedUrl = '<YOUR-FEED-URL>'
$twitterAccessSecret = '<TWITTER-ACCESS-SECRET>'
$twitterAccessToken = '<TWITTER-ACCESS-TOKEN>'
$twitterConsumerKey = '<TWITTER-CONSUMER-KEY>'
$twitterConsumeSecret = '<TWITTER-CONSUMER-SECRET>'
$bitlyOauthToken = '<BITLY-OAUTH-TOKEN>'

Now we can log into Azure using AZ CLI and create a resource group to hold our Function and storage account.

az login
az account set --subscription $subscription
az group create --name $resourceGroup --location $region

Create a new storage account and retrieve the connection string to it.

az storage account create --resource-group $resourceGroup --name $storageAcct --location $region --sku Standard_LRS
$storageConnStr = az storage account show-connection-string --resource-group $resourceGroup --name $storageAcct --output tsv

Create a storage container and upload the empty tracker file. This file can be found in the GitHub repo here.

az storage container create --account-name $storageAcct --name $storageContainerName
az storage blob upload --account-name $storageAcct --container-name $storageContainerName --name posts.json --file ./posts.json

Now create the Function App and set the application settings.

az functionapp create --resource-group $resourceGroup --name $functionApp --storage-account $storageAcct --consumption-plan-location $region
az functionapp config appsettings set --resource-group $resourceGroup --name $functionApp --settings "FUNCTIONS_EXTENSION_VERSION = ~1"
az functionapp config appsettings set --resource-group $resourceGroup --name $functionApp --settings "BLOG_FEED_URL = $blogFeedUrl"
az functionapp config appsettings set --resource-group $resourceGroup --name $functionApp --settings "TWITTER_ACCESS_SECRET = $twitterAccessSecret"
az functionapp config appsettings set --resource-group $resourceGroup --name $functionApp --settings "TWITTER_ACCESS_TOKEN = $twitterAccessToken"
az functionapp config appsettings set --resource-group $resourceGroup --name $functionApp --settings "TWITTER_CONSUMER_KEY = $twitterConsumerKey"
az functionapp config appsettings set --resource-group $resourceGroup --name $functionApp --settings "TWITTER_CONSUMER_SECRET = $twitterConsumeSecret"
az functionapp config appsettings set --resource-group $resourceGroup --name $functionApp --settings "BITLY_OAUTH_TOKEN = $bitlyOauthToken"
az functionapp config appsettings set --resource-group $resourceGroup --name $functionApp --settings "blogarchivetweeter_STORAGE = $storageConnStr"

Now we have to deploy the actual function. To do this, we’ll zip up the entire GitHub repository and deploy it into the Function App.

Compress-Archive -Path * -DestinationPath function.zip
az functionapp deployment source config-zip --resource-group $resourceGroup --name $functionApp --src ./function.zip

Summary

That’s it. At this point, you should have both a Function App and storage account deployed in the resource group with the function triggering based on a timer. Make sure to replace all the relevant settings for your Azure environment, Twitter/Bitly credentials, and blog feed URL.

Now you have a serverless blog post tweeter happily sending out your past blog posts to your followers.

Happy tweeting!

Cheers.

DEV Community: Brandon Olin [1x Engineer]

9 Tips for Writing Better PowerShell Functions

TOC

Tip #1: Functions Should Do One Thing

Tip #2: Functions Should Be Testable

Tip #3: Functions Should Be Self-Contained

Tip #4: Add Comment-Based Help

Tip #5: Use The PowerShell Function Naming Convention

Tip #6: Leverage Advanced Functions

Tip #7: Support the Pipeline

Tip #8: Support -WhatIf If Making Changes

Tip #9: Support -Confirm if Making Changes

Closing

Infrastructure Testing with Pester and the Operation Validation Framework

What about your Infrastructure?

Operation Validation?

Get-Answer.ps1

Get-Answer.tests.ps1

os.services.tests.ps1

Operation Validation Framework

Folder Structure

services.tests.ps1

logicaldisk.tests.ps1

Wrapping Up

Further reading

Using PoshBot Middleware for Rate-Limiting Notifications in Slack

PoshBot Middleware

Middleware Hook Stages

Adding the Middleware Hook

rate_limiting_notice.ps1

Summary

Joining Paths in PowerShell

Using a hard-coded string

Using Join-Path

Joining three or more paths

Dipping into .NET

Using a Powershell Azure Function to Send Automated Blog Post Tweets

TL;DR

Blog Post JSON feed

The Azure Function

run.ps1

function.json

Deploying the Function

Summary