Just the other day, I wrote a small script to
- download multiple swagger json files from services
- download the swagger-to-PDF tool
- generate a single pdf with all api endpoints
Now developers don’t even have to know which tool we use to generate our api documentation. They see the script, run it, and have the pdf file.
Furthermore the tool just automatically identifies which API versions are available.
Table of Contents
Why PowerShell? Well, it is preinstalled on Windows and easy to install on macOS and Linux.
Installing most other scripting languages on Windows is complicated.
My main motivation here is to keep the entrance barrier as low as possible. Enable everyone on your team.
If your team is already familiar with another cross-platform scripting solution (e.g. bash on windows via Cygwin), you already have all you need for our series on DevOps. In that case you can skip this one for the series.
For this tutorial, we need PowerShell and Visual Studio Code.
For installation steps, follow this guide by microsoft for your operating system.
On Windows, the installation of PowerShell 7 is optional. However, some advanced scripts will require PowerShell 7.
Extra Step for Windows
Before running PowerShell scripts on Windows, you must run
On macOS and Linux, Unrestricted is the default.
For more information, see microsoft’s documentation on Execution Policies.
Visual Studio Code
Now let’s download and install Visual Studio Code from Microsoft.
Visual Studio Code offers coding assistance and even debugging functionality for PowerShell. So we will be using visual studio code as free cross-platform script editor within this tutorial.
If you prefer a different editor, I still recommend using Visual Studio Code for this tutorial. After the tutorial, you should check if your preferred editor has the same debugging functionality.
After getting comfortable with moving around your file system, let’s write your first script.
Open Visual Studio Code and create a new file and save it with the .ps1 ending.
This way Visual Studio Code will recognize it as PowerShell script and offer a play button in the top right.
Also I can really recommend reading Microsoft’s Guides to Debugging PowerShell with Visual Studio Code to learn how to use Breakpoints and Watches.
As they use different default shells, the first line of your cross-platform script will tell macOS and Linux, that this is a PowerShell script.
pwsh is the command name for PowerShell in macOS and linux.
In PowerShell, you have different possibilities to write output.
While Write-Host is okay to give the user information on the state of your script. However, Write-Object, Write-Error Write-Debug and Write-Verbose will be important for advanced scripts.
It’s a good idea to be very verbose and always tell the script-user what’s happening.
So we can use
Write-Host "Copying files, please wait." to display exactly this text to the console.
Variables in PowerShell are names with a prefixed $ sign.
e.g. $count, $foldername, $date, etc.
The main advantage of PowerShell is its object orientation.
Assuming that your script is called test.ps1, we can read this files properties:
You can use Visual Studio Codes Watch function to examine your script’s objects.
As this would be a lot to cover, we will have a closer look at PowerShells object orientation later on. For now, just keep this fact in mind.
I always recommend enabling Strict Mode in all your scripts.
This is basically your standard second line after the she-bang.
It causes your scripts to abort when using uninitialized variables, non-existant properties etc.
See Microsofts documentation for detailed information on strict mode.
Microsoft has a super documentation on if-else in PowerShell, including many great examples.
Therefore I only want to show one example here for completeness.
Microsoft also has a super documentation on loops in PowerShell, so this example is also quite short.
As PowerShell is object oriented, I tend to use ForEach normally.
While Loops are quite rare in my scripts.
See more more great examples at Microsoft’s documentation:
PowerShell is very popular, so you can google “How to <DO ANYTHING> in PowerShell“.
The following are among some of my favourite resources:
- Official PowerShell Documentation
- Strongly Typed Variables in PowerShell
- Parameters in PowerShell Scripts
- PowerShell Guru Best Practices
- Arrays in PowerShell
With this basic scripting knowledge, we are able to get started automating in the upcoming episodes of our DevOps Guide.
While most scripts will only run very few commands, these are a few commands that you and your colleagues save every day. And let’s not forget the manual errors avoided by your scripts.
We can use them for builds, deployments, tests, project setup, anything!