Below are some alternative asynchronous options for seeing the output of commands they run.

Print Screen

An easy option is to use the PrtSc (or Print Screen) key to capture the whole screen, or Alt + PrtSc to capture just the active window.

This will copy the screenshot to their clipboard, which they can then paste into a Slack or Teams message or email.

A screenshot is nice and easy, unless the entire output does not fit nicely in a single image, or if you want to be able to copy and paste the output yourself.

Terminal command options

To get the output of a command, you can ask them to run the command and copy the output to the clipboard.

Manually copying the output is not always easy though, as many terminals use block selection which is unintuitive and makes it hard to copy the entire output, especially if the output is long and requires scrolling.

Instead, we can simply adjust the command they are running to automatically copy the output to the clipboard or save it to a file, which they can then send to you via Slack, Teams, email, etc.

Capture command output to the clipboard

Simply append | clip to the end of the command to copy the output to the clipboard, preserving the formatting.

For example, instead of just running:

Get-Process

They can run:

Get-Process | clip

This works for the output of any command or executable, not just PowerShell commands. For example:

dsregcmd /status | clip

This works in both PowerShell and the old-school Command Prompt.

In PowerShell, clip is the alias for Set-Clipboard, which is a built-in PowerShell cmdlet that copies input to the clipboard.

There is also a clip.exe executable too, so if you are in WSL or Git Bash, you can use clip.exe to copy the output to the Windows clipboard. e.g.

ps | clip.exe

clip.exe will even work in PowerShell and Command Prompt, so you can always use it in place of clip if you like.

A downside to this method is that the output is not visible in the terminal; it is only copied to the clipboard.

Capture command output to a file

You can use the >> operator to redirect the output of a command to a file. e.g.

Get-Process >> C:\temp\output.txt

In PowerShell, the >> operator is an alias for Out-File, which is a built-in PowerShell cmdlet that writes output to a text file. e.g.

Get-Process | Out-File -FilePath C:\temp\output.txt -Append

The >> operator works in other shells too, like Command Prompt and Bash, so it’s a good one to know.

The >> operator will append the output to the file if it already exists, while using just > will overwrite the file if it already exists. Using >> allows you to run multiple commands and capture all of the output to the same file.

A downside of this approach is the output is not written to the terminal; it is only written to the file.

Capture command output to both the terminal and a file

We can use Tee to see the output in the terminal and save it to a file. e.g.

Get-Process | Tee C:\temp\output.txt

This will write the output to both the terminal and the file.

In PowerShell, Tee is an alias for Tee-Object. The full command syntax could look like this:

Get-Process | Tee-Object -FilePath C:\temp\output.txt

tee exists in other shells as well like Bash, so using the shorthand syntax will work pretty much everywhere. e.g.

ps | tee output.txt

Start a transcript to capture all output from the terminal session

PowerShell has a built-in transcript feature that can capture all output from a terminal session and save it to a file. This is great if you want to capture the output of multiple commands.

To start a transcript, simply run the Start-Transcript cmdlet and specify the path to the file where you want to save the transcript. Then run the various commands you want to capture the output of. When you’re done, run the Stop-Transcript cmdlet to stop the transcript and save the file.

Start-Transcript -Path C:\temp\transcript.txt

# Run various commands here
Get-Process
Get-Service
dsregcmd /status

Stop-Transcript

The transcript text file can then be sent to you via Slack, Teams, email, etc.

This method only works for PowerShell.

Conclusion

While screen sharing is often the best way to interactively help someone and see the output of commands in real time, it’s not always possible. Taking screenshots is easy and effective, except in the case of long outputs that don’t fit on a single screen, or when you want to be able to copy and paste the output yourself.

Luckily, there are several easy options for capturing terminal output to a file or the clipboard, which can then be shared via Slack, Teams, email, etc.

I hope you’ve found this post informative and it helps you when working with others remotely!

Happy helping and troubleshooting! 😊

Normally when you run a kubectl command, you get back a wall of boring grey text. With kubecolor, you get informative, colourful output like this:

I especially appreciate how errors are highlighted red, making them easy to spot.

Kubecolor installation

Kubecolor is cross-platform, easy to install, and has great installation documentation.

For example, installing it on Windows is as easy as running:

winget install --id Kubecolor.kubecolor

Setup to use kubecolor by default

The Kubecolor documentation also has great setup instructions for many shells, including PowerShell.

You can typically set up an alias so that anytime you run kubectl, it automatically uses kubecolor. Better yet, instead of having to type kubectl every time, just type k instead!

Here’s how you can set that up in PowerShell:

Set-Alias -Name kubectl -Value kubecolor
Set-Alias -Name k -Value kubectl

Now you can run k get pods and see colourful output by default.

Setup kubectl command and parameter completions

The documentation also has instructions for setting up kubectl completions in many shells, which is super handy.

This is how it can be done in PowerShell:

kubectl completion powershell | Out-String | Invoke-Expression
Register-ArgumentCompleter -CommandName 'k','kubectl','kubecolor' -ScriptBlock $__kubectlCompleterBlock

Now you can type k get p and hit Tab and it will auto-complete. Continue hitting Tab to cycle through the available options, or use Ctrl + Space to see all available options.

This works for both command names and parameter values, making it easier to discover kubectl commands and custom resources in your cluster. Try typing each of the following and hitting Ctrl + Space. Note the trailing space at the end of each:

• k
• k get
• k get pods -n

Automatic setup with PowerShell profile

You don’t want to have to run the setup commands every time you open PowerShell though. You can use your PowerShell profile to run the code automatically every time PowerShell starts.

In PowerShell, you can find the path to your PowerShell profile by running:

$PROFILE

To open the file in Notepad, run:

notepad $PROFILE

Create the file if it doesn’t exist, and add the following code to it:

# If kubecolor is installed, alias kubectl to use it.
if (Get-Command kubecolor -ErrorAction SilentlyContinue)
{
  Set-Alias -Name kubectl -Value kubecolor
}

# If kubectl is installed, register the argument completions for kubectl and its aliases.
if (Get-Command kubectl -ErrorAction SilentlyContinue)
{
  Set-Alias -Name k -Value kubectl
  kubectl completion powershell | Out-String | Invoke-Expression
  Register-ArgumentCompleter -CommandName 'k','kubectl','kubecolor' -ScriptBlock $__kubectlCompleterBlock
}

That’s it!

To test it out, open a new PowerShell window and run k version or k get pods. You should see beautiful, colourful output.

Colour themes

Kubecolor comes with several built-in colour themes, including light and dark themes. It even allows you to create your own custom themes. See the documentation for more info.

Conclusion

So now you get beautiful, colourful kubectl output that is easier to read and understand at a glance. You also get to type less by using the k alias, and improve discoverability with command and parameter completions.

I hope you found this useful.

Happy Kuberneting!

If you enjoyed this post, you might also like this post on using Oh My Posh and updating your terminal to use different fonts.

For commands that produce a lot of output, consider redirecting the output to a text file for easier reading. You can do this by appending > filename.txt to the command. Another option is appending | clip when using PowerShell to copy the output directly to the clipboard so you can paste it in a text editor.

I intend to keep updating this list as I discover more useful commands. If you know of others, please let me know in the comments.

If you like these, you might also like my Common Run commands to access various Windows settings and apps post.

I hope you find these helpful. Happy computing!

But this isn’t about those mice; it’s about the Logitech MX Master 4, which was released in October 2024, and how I found it compared to the MX Master 3s.

This is not meant to be a comprehensive review; just my personal experience and what stood out to me.

Why I got the MX Master 3s

I’ve been using the Logitech MX Master 3s for almost 2 years now. I got it because I started having wrist pain, and thought a more ergonomic mouse might help.

I first tried the Logitech MX Vertical, but didn’t like how I had to move my entire arm to move the mouse. I then tried the MX Master 3s. It was super comfortable, had all of the essential buttons (left, right, middle, back, forward, and scroll wheel), as well as a thumb wheel and gesture thumb button. I loved that all of the buttons were programmable too, via the Logi Options+ app. The thumb gesture button allows you to click it, as well as hold it and move the mouse up/down/left/right to trigger actions, so I have mine configured to control my media (play/pause, volume up/down, next/previous track).

After using it for a couple weeks my wrist pain went away, and I had a new favourite mouse!

Let my pain be a lesson kids. Invest in an ergonomic mouse and keyboard now, before you develop problems!

A common problem with the MX Master 3s

I love the MX Master 3s. After almost 2 years though, it started having flaky issues with left button clicks. Sometimes it would not register single clicks, or would double-click when I only clicked once. It also made dragging-and-dropping very difficult, as most times it would release the drag before I let go of the button.

After some research, I found that this is a common issue with the MX Master 3s and the typical fix is to replace the button switch (as shown in this YouTube video), which requires taking the mouse apart and soldering. While I like to imagine myself as a DIY guy, I’ve never soldered before and don’t have the tools on hand.

Instead, I took the mouse apart and applied a couple pieces of tape to the mouse casing above the switch to increase the tension on it (also shown in the above YouTube video). This helped a bit and the issues were less frequent, but didn’t totally fix the issue. A week later I also applied a drop of WD-40 to the switch, as mentioned on Reddit. This has my 3s working normally again, at least for now.

Trying out the MX Master 4

Since the MX Master 4 had just come out, I figured it was a good time to upgrade, as I wasn’t sure how long my temporary fix to my 3s would last.

Unfortunately, it sounds like the MX Master 4 uses the same button switches as the 3s, so they will likely have the same issue eventually. Time will tell.

Below is a breakdown of how I found the MX Master 4 compared to the 3s.

✅ MX Master 4 Pros:

• I like the thumb wheel better. It sits closer to the tip of my thumb, making it more comfortable to use.
• Has an extra programmable gesture button in front of the forward button, which was a compelling reason to upgrade.
• The haptic feedback (vibration) is neat, but not really useful. The only time I notice it is when waking the mouse and using the Actions Ring. Right now very few apps make use of it, but that may change in the future.
• Screws to take it apart do not require removing the feet pads, like the 3s.
  • Uses 6 phillips screws, which is nice. The 3s uses 5 phillips screws and 1 torx screw, which was annoying as I had to hunt down a torx screwdriver.
• Feels very similar to the MX Master 3s in terms of shape, size, and button layout, and uses the same Logi Options+ app, so upgrading felt smooth.

❌ MX Master 4 Cons:

• It feels quite a bit heavier than the 3s. The specs say it’s only 9 grams heavier (150g vs 141g), but it feels like more.
  • I was getting wrist pain a couple years back, and the 3s alleviated that for nearly 2 years. After using the 4 for a little over a week, the wrist pain returned.
• The thumb button is triggered by pressing down or in, so I often press it in by accident when adjusting the mouse new position on my desk, such as when changing my sitting position.
  • In the 3s, you have to press the thumb button down, allowing you to easily pick up the mouse (by squeezing your thumb in) without accidentally pressing the button.
  • The 4 is both heavier and smoother than the 3s. Even with the textured bumps on the thumb button, it’s quite slippery, making the thumb slide when picking it up and forcing you to grip it tighter, leading to accidental presses.
  • I found this mentioned in several other online reviews as well, so I know it’s not just me.
  • I change the thumb button to media controls (the default action is the Actions Ring), so more than once I accidentally pressed the thumb button while adjusting the mouse position on my desk and started playing music while on a video call (embarrassing! 🫠).
• The gesture button is so far forward it’s a bit hard to reach with my thumb.
  • It’s not a huge issue, but I noticed myself having to consciously think about reaching for it. That could change and become muscle memory over time though.
• The scroll wheel button to switch between ratchet and free-spin modes makes a noticeable click sound, where it is silent on the 3s. This doesn’t really bother me though; just something I noticed.

The feel of the MX 4 in my hand is very similar to the 3s. The 3s is a bit grippier due to the rubberized surface, while the MX 4 has a smoother plastic finish. I didn’t mind the feel, but considering the MX 4 is heavier, it could have benefitted from the grippier surface. The shape is nearly identical, with only very minor differences.

If I didn’t feel them side-by-side, it would be hard to tell which is which, aside from the weight difference and the feel of the thumb button. If you like the feel of the MX 3s, you’ll likely like the MX 4 as well.

I’ll note that I use Bluetooth for both, so I can’t comment on the performance of the included Logi Bolt USB receiver. I can say though that the 3s uses a USB-A port, while the 4 uses USB-C, so you may need to consider how many open ports you have.

Also, while I have used both mice for video games, I don’t play competitive or fast-paced games where low millisecond response times make a difference. Both mice perform completely fine for my casual gaming needs. Others have commented that if you need high polling rates, neither of these mice are ideal and you should invest in a proper gaming mouse.

Here’s a few pics to visually compare the two, with the 3s being the black one (bottom/left) and the 4 the graphite (grey) one:

Conclusion

While I quite liked the MX Master 4, especially for the extra programmable button, the wrist pain due to increased weight and accidental thumb button presses were a deal-breaker for me.

I ended up returning my MX Master 4 and will likely be ordering another 3s if the click issues return. If I was still in my 20s and hadn’t developed wrist pain, I likely would have kept the MX 4.

If Logitech releases a followup version that’s a bit lighter and addresses the accidental thumb button presses, I would try it out again.

I don’t often do product reviews or comparisons, so if you enjoyed this leave a comment and let me know!

Background

Dave Callan, a fellow Microsoft MVP, recently asked on LinkedIn if .NET developers prefer to use .First(), .FirstOrDefault(), .Single(), or .SingleOrDefault() when they expect exactly one item in a collection.

I’ve written about this very subject, so I commented with a link to my blog post where I state that I prefer to always use .FirstOrDefault() because it allows me to provide a descriptive custom error message, which can make troubleshooting much easier. Dave replied that he prefers to use .Single(), even though it gives a generic error message, and rely on observability tools to troubleshoot issues when they arise; especially for issues that “should never happen”.

This got me thinking about whether observability tools can truly replace good custom error messages.

Observability is awesome

If you’re not familiar with OpenTelemetry (OTEL), it’s a standard set of APIs for collecting metrics, traces, and logs from your application, giving you observability into its behavior. You create spans to track how long an operation takes, and add attributes to those spans to provide additional context. The attributes can be things specific to the operation, such as the user or items involved in the operation, or more general information, such as the environment, version of the application, or the operating system it’s running on.

You then export the OTEL data into an observability tool, which allows you to visualize and query the data. This allows you to answer questions like:

• Which company, user, or region has the most failed requests this week?
• What is the average response time for requests to a specific endpoint? Which endpoints are the slowest?
• What do failing requests have in common? e.g. a specific user, company, server, region, browser, app version, etc.
• What were the headers, parameters, or payload of a specific request?

It also allows for distributed tracing, letting you see how individual requests flow through your application and its dependencies (e.g. other services, database calls, etc.), allowing you to pinpoint where things went wrong or spot potential bottlenecks between components.

There’s no question that adding OTEL instrumentation to your application can provide valuable insights into its behavior. It provides additional information, allowing you to troubleshoot issues and spot trends before they become problems. When possible, you should absolutely add OTEL instrumentation to your application.

Should observability replace custom error messages though?

To be clear, I’m not talking about simply catching an exception and rewriting it with a more user-friendly message. I’m talking about including specific data that may have led to the error, such as the parameter values that were used, the dataset that was being queried, or any other relevant context that could aid in troubleshooting.

Here’s some typical code that would throw an exception with a generic error message:

var people = new List<string> { "Alfred Archer", "Billy Baller", "Billy Bob", "Cathy Carter" };
var name = "Zane";

// Throws generic exception: System.InvalidOperationException: Sequence contains no matching element
var zane = people.First(x => x.StartsWith(name));

And modified code that provides a more descriptive custom error message:

var people = new List<string> { "Alfred Archer", "Billy Baller", "Billy Bob", "Cathy Carter" };
var name = "Zane";

try
{
    var zane = people.First(x => x.StartsWith(name));
}
catch (InvalidOperationException ex)
{
    throw new PersonNotFoundException($"Could not find a person named '{name}' in the people list.", ex);
}

Notice that the custom error message provides the name of the person that was being searched for, which can be tremendously helpful when troubleshooting. It makes it easy to know the exact name, and verify there were no typos or unexpected characters. e.g. They searched for “ Zane “ (with spaces), or “Zone” instead of “Zane”.

Be mindful to not include sensitive information in error messages, such as passwords or personal data.

We could have also added OTEL instrumentation to the code, creating a span for the operation and adding attributes for the name being searched for.

Even if we had added OTEL instrumentation, I would argue that custom error messages are still valuable for a number of reasons:

Quicker troubleshooting

• Custom error messages can provide immediate context about what went wrong, and can be surfaced in different ways:
  • Shown in the observability tooling.
  • Logged in application logs (local or remote), separate from the observability tooling.
  • Displayed to the user, if appropriate.
• Allows developers to identify problems faster, as they don’t need to query the observability tooling and follow breadcrumbs to find the relevant information.
• Potentially allows users to self-serve and resolve issues on their own, if the error message is displayed to them.
  • If a user presses a button to submit a form and sees the error message “System.InvalidOperationException: Sequence contains more than one matching element”, they may not know what to do. However, if they see “Error: More than one user found with the email address ‘me@example.com’”, they have a clearer understanding of the issue and can potentially resolve it themselves.
  • Allowing users or support staff to resolve issues on their own saves both users and developers time, making everyone happier.

Do observability tools have the data you need?

• Observability tooling relies on the data that is sent to it. If the necessary data is not being captured, it may not be available when you need it.
• Custom error messages can provide additional context only when its needed.
  • For example, a custom error message may include the parameters that were used for a specific query, or the dataset that was being queried, whereas you may not want to log that information for every request in your observability tooling.
• Do you have every component in the chain instrumented?
  • If your application calls an external service or third-party library that is not instrumented, it may not have the necessary data to help troubleshoot an issue.

Budgets change, or are non-existent

• Observability tooling can be expensive, and not all organizations have the budget for it.
• Even if your organization has the budget now, it may not in the future.
• Many organizations implement sampling to reduce costs (e.g. only retain 20% of traces), which means you may not have the necessary data to troubleshoot a specific issue.

Access to observability tooling

• Not all developers may have access to the observability tooling, especially in larger organizations, or where you pay per user.
  • Does every team member have access to the tooling? What about support staff?

Team members change

• Do all team members know how to effectively use the observability tooling?
  • Team members who are familiar with the tools may leave the organization.
  • New team members may not be familiar with the observability tools, know where to find them, or even know they exist.

Observability tooling changes

• Organizations may change observability providers (e.g. New Relic to Datadog to Honeycomb to …), which means team members may need to learn new tools.
• Have all of the old apps and services been updated to send data to the new observability provider?

Aside: I’m a huge fan of Honeycomb.io.

The type of application matters

• Do users expect a desktop/mobile application to be sending observability data over the network?
• If not stored remotely, do users expect your app to store all of that observability data locally?
• Users may not want an application to send or store observability data at all, due to privacy, data usage, or performance concerns.

Conclusion

It probably seems obvious that it’s preferable to include information in the error message that can help troubleshoot the issue. I can’t tell you though how many times I’ve been frustrated, both as a user and as a developer, by generic error messages that provide no context about what went wrong.

I’m of the opinion that the more information you can provide when an error occurs, the better. There’s no doubt that observability can provide additional information that can help troubleshoot issues. However, there’s no guarantee that it will provide the same information that a well-crafted custom error message can provide, or that the observability data will be available when you need it.

A developer spending an extra couple of minutes writing a custom error message that provides additional context can save hours, even days, of troubleshooting time later on. Even if it’s not an error message the end-user will see, it can still be tremendously helpful for developers and support staff.

So the next time you’re performing an operation that may potentially throw an exception, consider whether catching and re-throwing the exception with additional context information may be beneficial.

Happy coding!

Note that Win is the Windows key.

If you enjoy this post, check out my Windows settings I change after a clean install post.

Windows shortcuts

You can use the following shortcuts regardless of the application you’re in:

• Alt + Tab: Cycle between open windows.

• Alt + Shift + Tab: Cycle between open windows in reverse.

• Win + Up: Maximize the current window.
• Win + Down: Restore / Minimize the current window.
• Win + Left / Right: Snap the current window to the left or right side of the screen.
• Win + Shift + Left / Right: Move the current window to the left or right monitor (only works with multiple monitors set up).

• Win + Alt + Left / Right / Up / Down: Snap the current window to a specific quadrant of the screen (Windows 11 only).

• Win + Tab: Open Task View to see all virtual desktops and all windows in the current virtual desktop.
• Win + Ctrl + D: Create a new virtual desktop.

• Win + Ctrl + Left / Right: Switch between virtual desktops.

• Win + D: Minimize all windows; press again to restore all windows.
• Win + E: Open File Explorer.
• Win + R: Open the Run dialog.
• Win + P: Open the Project menu (for connecting to external displays).
• Win + I: Open Settings.
• Win + L: Lock the computer.

• Ctrl + Shift + Esc: Open Task Manager.

• Win + A: Open the Action Center.

  • Contains controls for Wi-Fi, Bluetooth, Airplane mode, volume, brightness, and more.

    

• Win + X: Open the Quick Link menu.

  • Contains links to many system tools, such as Installed Apps, Device Manager, Sign out, Shut down etc.

    

  • I often use Win + X followed by A to open an elevated terminal window.

• Win + Period, or Win + Semicolon: Open the emoji picker 🤩.
  • Once in the emoji picker, type to search, use Shift + Arrow keys to navigate, Enter to insert the emoji, and Esc to close the picker.
• Win + V: Open Clipboard history to paste things copied in the past.
  • It’s nice that this is built into Windows 10+, but I prefer to use Ditto Clipboard Manager instead. See my YouTube video on using Ditto, and the followup video showing more features.
• Win + Shift + S: Take a screenshot of part of the screen and edit it with the Snipping Tool.
  • I prefer to use ShareX instead, which has many more features.
  • Windows 11 has greatly improved the Snipping Tool, including adding shapes to the image editor and the ability to take video as well. It is a great built-in option if you don’t want to install a third-party app.
  • On Windows 10 I would recommend Greenshot if you don’t want all of the advanced features of ShareX.
• Ctrl + Shift + Win + B: Restart the graphics driver.
  • This is useful if your screen is not drawing properly or one of your monitors stops displaying.

Applications that support multiple tabs (e.g. web browsers, text editors, File Explorer on Windows 11+) often support:

• Ctrl + Tab to cycle between tabs in the application.
• Ctrl + Shift + Tab to cycle between tabs in reverse.

The functionality may vary depending on the application though.

Taskbar shortcuts

The taskbar is the bar typically at the bottom of the screen that contains the Start button, pinned applications, open windows, and the system tray. There are a few shortcuts you can use when clicking on an application in the task bar:

• Shift + Left-click: Opens another instance of the application.
• Ctrl + Shift + Left-click: Opens another instance of the application as an administrator.
• Shift + Right-click: Show additional context menu options, such as Run As Admin or a Different User.

File Explorer shortcuts

When in the File Explorer, you can use the following shortcuts:

• Alt + Up: Go up one level in the folder hierarchy.
• Alt + Left: Go back.

• Alt + Right: Go forward.

• Ctrl + N: Open a new File Explorer window at the current folder.
• Ctrl + T: Open a new tab (Windows 11+).

• Ctrl + Shift + N: Create a new folder.

• Alt + D: Focus the address bar so you can type in it.
• Alt + Enter: Show properties for the selected file/folder.
• F2: Rename the selected file/folder.

• Shift + Delete: Permanently delete the selected items without moving them to the Recycle Bin.

• Ctrl + A: Select all items in the current view.
• Hold Shift and click to select a range of items.
• Hold Ctrl and click to select multiple individual items.
• Just start typing the name of a file or folder to quickly jump to and select it.

Many of the above shortcuts also work in other applications, such as web browsers and text editors.

In the File Explorer address bar (or the Run dialog window), you can type:

• cmd to open a command prompt in the current folder.
• pwsh to open a PowerShell 7+ prompt in the current folder, if you have it installed.
• shell:startup to open the Startup folder of the current user.
  • Placing a shortcut to an application in this folder will make it start automatically when you log in.
• shell:sendto to open the SendTo folder of the current user.
  • Placing a shortcut to an application in this folder will make it appear in the Send To context menu when you right-click a file or folder.
• shell:common startup to open the Startup folder for all users.
• shell:common sendto to open the SendTo folder for all users.
• shell:desktop to open the Desktop folder.
• shell:downloads to open the Downloads folder.
• shell:appsfolder to see all installed applications, including hidden ones, and right-click to uninstall ones you don’t need.

See my YouTube video on File Explorer shortcuts for more!

Conclusion

Learning and using keyboard shortcuts can significantly improve your productivity. Try to incorporate a few of these shortcuts into your daily routine.

As I discover move great shortcuts I’ll update this post, so be sure to check back for updates!

Know of a great shortcut that I missed? Please let me know in the comments!

NOTE: Using long-lived secrets can increase the risk of exposure, so it’s typically not recommended for production applications. Especially for secrets that would grant access to sensitive resources or data, or that have high privileges. A better approach is to use short-lived secrets and automate rotating them regularly. Even better, use Federated Identity Credentials and avoid secrets and expirations altogether.

To create an Azure app registration (i.e. service principal) secret with an expiry longer than 2 years, you can use the Azure CLI. Here’s an example command that creates a secret with a 5 year expiry, where <application-id> is the Application (Client) ID of your app registration:

az ad app credential reset --id <application-id> --years 5

This will create a new secret on the app registration and output the password, which is the secret value. Be sure to copy the value and store it somewhere secure, such as an Azure Key Vault, as you will not be able to retrieve it again.

You can do the same operation in PowerShell using the Az PowerShell module (specifically the Az.Resources module) and the New-AzADAppCredential cmdlet, but you must use the app registration’s Object ID instead of the Application ID:

$startDate = (Get-Date)
$endDate = $startDate.AddYears(5)
New-AzADAppCredential -ObjectId <object-id> -StartDate $startDate -EndDate $endDate -DisplayName 'User friendly description'

Hopefully you (and my future self) find this helpful.

Happy coding!

To make it both easier to remember commands I rarely use, and to reduce the number of keystrokes needed to execute the ones I use all the time, I use Git aliases.

Show me the code!

I go over each alias in detail below, but here’s the alias section taken directly from my current global .gitconfig file in my user directory. e.g. C:\Users\[Your Name]\.gitconfig on Windows, or ~/.gitconfig on Linux/Mac.

[alias]
  alias = !echo 'git config --get-regexp ^alias\\.' && git config --get-regexp ^alias\\.
  ac = !echo 'git add -A , git commit -m' && git add -A && git commit -m
  b = !echo 'git branch' && git branch
  browse = !echo 'start `git config get remote.origin.url`' && start `git config get remote.origin.url`
  co = !echo 'git checkout' && git checkout
  commit-empty = !echo 'git commit --allow-empty -m \"chore: Empty commit to re-trigger build\"' && git commit --allow-empty -m \"chore: Empty commit to re-trigger build\"
  delete-local-branches-already-merged-in-remote = !echo 'git branch --merged | egrep -i -v(main|master|develop|dev|staging|release)| xargs -r git branch -d' && git branch --merged | egrep -i -v '(main|master|develop|dev|staging|release)' | xargs -r git branch -d
  delete-local-branches-already-merged-in-remote-what-if = !echo 'git branch --merged | egrep -i -v(main|master|develop|dev|staging|release)//| xargs -r git branch -d' && git branch --merged | egrep -i -v '(main|master|develop|dev|staging|release)'
  delete-local-tags = !echo 'git tag -l | xargs git tag -d && git fetch --tags' && git tag -l | xargs git tag -d && git fetch --tags
  delete-stale-remote-tracking-branches-from-local = !echo 'git remote prune origin' && git remote prune origin
  ge = !echo 'GitExtensions .' && GitExtensions .
  gec = !echo 'GitExtensions commit' && GitExtensions commit
  gtfo = !echo 'git reset --hard , git clean -xfd' && git reset --hard && git clean -xfd
  history = !echo 'git log --oneline --graph --decorate --all' && git log --oneline --graph --decorate --all
  s = !echo 'git status' && git status
  pushf = !echo 'git push --force-with-lease' && git push --force-with-lease
  pushnew = !echo 'git push --set-upstream origin branch_name' && git push --set-upstream origin `git symbolic-ref --short HEAD`
  stashall = !echo 'git stash push --include-untracked' && git stash push --include-untracked

You will notice that each alias begins with !echo '...' &&. This is not mandatory and you can remove it if you like; it will simply print the command to the console before executing it, so that you can see the actual commands being run.

For brevity, I will not include the !echo '...' && part in the explanations below.

Updating your .gitconfig file

To add these aliases to your global .gitconfig file, you can either:

1. Use the git config command to add them one by one.

   • For example, to add the ac alias, you can run the following command in your terminal:

      git config --global alias.ac '!echo "git add -A , git commit -m" && git add -A && git commit -m'
     

2. To mass edit, open the file in a text editor and add them manually.

   • To open the file in the default editor, use the following command:

      git config edit --global
     

Individual aliases in detail

alias = git config --get-regexp ^alias\\.

Typing git alias will show you all the aliases you have set up in your .gitconfig file.

ac = git add -A && git commit -m

Typing git ac "The commit message" will add all changes to the staging area and commit them with the provided message.

b = git branch

Typing git b will show you all the branches in your local repository. This alias just saves a few keystrokes.

browse = start `git config get remote.origin.url`

Typing git browse will open the remote repository in your default web browser.

Tip: Use this to open the repository in GitHub, Azure DevOps, Bitbucket, etc. to create pull requests after committing changes to a branch and pushing them up, if you prefer the PR creation web experience to the IDE experience.

Note: start is a Windows command to open a file or URL in the default application. You may need to adjust this for the Linux/Mac equivalent, which is may be open for Mac and xdg-open for Linux.

co = git checkout

Typing git co branch_name will switch to the specified branch. This alias just saves a few keystrokes.

commit-empty = git commit --allow-empty -m \"chore: Empty commit to re-trigger build\"

Typing git commit-empty will create an empty commit with the message chore: Empty commit to re-trigger build. This is useful for re-triggering builds in CI/CD pipelines without making any code changes.

delete-local-branches-already-merged-in-remote = git branch --merged | egrep -i -v '(main|master|develop|dev|staging|release)' | xargs -r git branch -d

Typing git delete-local-branches-already-merged-in-remote will delete all local branches that have already been merged into the remote repository, except for the specified branches (main, master, develop, dev, staging, release). This is useful for cleaning up your local branches after merging pull requests.

Tip: Change the branches in the egrep command to match your own branch names that you never want it to delete.

Tip: If you don’t like the long verbose alias name, give it a new one! 😊

delete-local-branches-already-merged-in-remote-what-if = git branch --merged | egrep -i -v '(main|master|develop|dev|staging|release)'

Typing git delete-local-branches-already-merged-in-remote-what-if will show you all local branches that would be deleted if you ran the delete-local-branches-already-merged-in-remote alias command.

delete-local-tags = git tag -l | xargs git tag -d && git fetch --tags

Typing git delete-local-tags will delete all local tags and fetch the latest tags from the remote repository, ensuring that your local tags exactly match the remote’s.

delete-stale-remote-tracking-branches-from-local = git remote prune origin

Typing git delete-stale-remote-tracking-branches-from-local will delete any stale remote-tracking branches from your local repository. That is, if a branch has been deleted from the remote repository, this will remove it from your local repository as well if needed.

ge = GitExtensions .

Typing git ge will open the GitExtensions GUI for the current repository. This requires having GitExtensions installed on your machine.

I use this when I’m not in an IDE, like VS Code, and want to view the history of branches and view their commits and diffs.

Tip: If you prefer a different git tool over GitExtensions, you may be able to replace GitExtensions with the name of your preferred tool.

gec = GitExtensions commit

Typing git gec will open the GitExtensions GUI for committing changes in the current repository. Again, this requires having GitExtensions installed on your machine.

I use this when I’m in the terminal and want a more rich and easy diff, stage, and commit experience than the command line provides.

Tip: Again, if you prefer a different git tool over GitExtensions, you may be able to use it if it accepts command line arguments.

gtfo = git reset --hard && git clean -xfd

Typing git gtfo will reset your current branch to the last commit, deleting any uncommitted changes and removing all untracked files and directories.

history = git log --oneline --graph --decorate --all

Typing git history will show you a more compact representation of the commit history for all branches in your repository.

Here is a sample output of the git history alias:

Compare that to the default git log output:

s = git status

Typing git s will show you the status of your current branch, including any uncommitted changes and the current branch name. This alias just saves a few keystrokes.

pushf = git push --force-with-lease

Typing git pushf will force push your changes to the remote repository, with a lease. This is useful when you need to overwrite the remote branch with your local changes, but you want to ensure that you don’t accidentally overwrite someone else’s changes by forgetting to add --force-with-lease.

pushnew = git push --set-upstream origin `git symbolic-ref --short HEAD`

Typing git pushnew will push your current branch to the remote repository and set the upstream branch to the same name. This is useful when you create a new branch locally and want to push it to the remote repository for the first time, and aren’t using an IDE that does this for you. This is similar to the git push --set-upstream origin branch_name command, but it automatically uses the name of the current branch.

stashall = git stash push --include-untracked

Typing git stashall will stash all changes in your working directory, including untracked files. This is useful when you want to temporarily save your changes without committing them, and you want to include untracked files as well.

Why aren’t you using PowerShell commands in the alias?

I’m a huge proponent of PowerShell, so you may be wondering why I’m using unix commands like xargs and egrep in my aliases. The main reason is that PowerShell is not installed by default on Linux and Mac. Git Bash is installed with Git though, so I believe the aliases should work on all platforms and in non-PowerShell shells.

Conclusion

I use these aliases to make my life easier when working with Git on the command line. Hopefully you’ve found some of them useful, or they’ve inspired you to create new ones not listed here. Feel free to customize these aliases to fit your preferences.

If you have suggestions for other aliases, please leave a comment below! If you found this post helpful, consider sharing it with friends and colleagues.

Happy coding!

The git clean command can be used to remove untracked files and free up disk space. However, running git clean -xfd in each repository manually can be a hassle. Luckily, we can automate this process using PowerShell.

Clean all repos using the GitClean PowerShell module

To make it easy to clean all your Git repositories, I created the cross-platform GitClean PowerShell module.

Assuming all of your Git repositories are located under a common root folder, C:\dev\Git for example, you can install the module and clean all your repos with the following PowerShell code:

Install-Module -Name GitClean
Invoke-GitClean -RootDirectoryPath 'C:\dev\Git'

In the screenshot above you can see it found 262 Git repositories, cleaned 260 of them, skipped cleaning 2 of them because they had untracked files that would have been lost, and freed up 33.4 GB of disk space. Easy 😊

No more node_modules of old projects taking up all my disk space 😅

Alternative PowerShell one-liner

Not everyone likes installing modules on their system, so as an alternative, here is a simple PowerShell script you can run to clean all your Git repositories:

[string] $rootDirectoryPath = 'C:\dev\Git'

# Find all '.git' directories below the given path.
Get-ChildItem -Path $rootDirectoryPath -Recurse -Depth 3 -Force -Directory -Filter '.git' |
    # Get the directory path of the Git repository.
    ForEach-Object {
        $gitDirectoryPath = $_.FullName
        $gitRepositoryDirectoryPath = Split-Path -Path $gitDirectoryPath -Parent
        Write-Output $gitRepositoryDirectoryPath
    } |
    # Only include Git repositories that do not have untracked files.
    Where-Object {
        $gitOutput = Invoke-Expression "git -C ""$_"" status" | Out-String
        [bool] $hasUntrackedFiles = $gitOutput.Contains('Untracked files')
        if ($hasUntrackedFiles) {
            Write-Warning "Skipping Git repository with untracked files: $_"
        }
        Write-Output (-not $hasUntrackedFiles)
    } |
    # Clean the Git repository.
    ForEach-Object {
        Write-Output "Cleaning Git repository: $_"
        Invoke-Expression "git -C ""$_"" clean -xdf"
    }

You can download this snippet as a script here.

This won’t give you the nice progress bars and detailed information that the GitClean module does, but it will get the job done.

Conclusion

It’s easy to forget to clean up old Git repositories. When you do remember to, the GitClean module can make it quick and painless. You might even want to create a scheduled task or cron job to run it automatically every month to keep your disk space in check.

I hope you find this module useful. Happy coding! 😊

This post was written with Windows 11 in mind, so some of the settings may not be available in other versions of Windows, or you may need to access them differently.

As I discover more awesome settings I’ll add them here, so be sure to check back from time to time. Also, if you have a favourite that I don’t have listed here, please let me know in the comments below.

If you enjoy this post, check out my My favourite Windows shortcuts post.

File Explorer settings

Have File Explorer open to the This PC view

By default, File Explorer opens to the Home view, which shows a bunch of things, such as your most used folders and files. I find that view very cluttered, and often just want to get into the root of one of my drives, so I prefer to start at the This PC view.

Below are screenshots of the default Home view and the This PC view:

To change the default view of File Explorer to This PC:

1. In the Start Menu, search for File Explorer Options and open it.
2. In the File Explorer Options window, change the Open File Explorer to setting to This PC.

Show hidden files and folders and file extensions in File Explorer

By default, File Explorer will not show hidden files and folders, nor show file extensions for known file types. I don’t like Windows hiding things from me, so I always enable these settings.

Below are screenshots showing how a directory in File Explorer might look before and after making the changes:

To enable the settings:

1. Open File Explorer Options.
   • You can search for File Explorer Options in the Start Menu, or find it in File Explorer by clicking the View tab, then Options on the right side (Windows 10), or the ... button then Options (Windows 11).
2. In the Folder Options window, click on the View tab.
3. Under Advanced settings, find the following settings:
   • Enable Show hidden files, folders, and drives
   • Disable Hide extensions for known file types
4. Click Apply to apply it to the current folder.
5. Click Apply to Folders to apply it to all folders.

The last step of clicking the Apply to Folders button is important so that you don’t have to do this for every folder you open.

Mouse settings

Show where the mouse cursor is with the Ctrl key

If you have multiple monitors, it’s easy to lose the mouse cursor. Windows has a feature that when you press the Ctrl key, it will show you where the mouse cursor is by briefly circling it.

To enable this feature:

1. Use the Start Menu to search for Mouse settings.
2. In the Mouse settings window, open the Additional mouse settings, which should pop up the Mouse Properties window.
3. Click on the Pointer Options tab.
4. Enable Show location of pointer when I press the CTRL key.

Bonus: See the Microsoft PowerToys section at the end to allow spotlighting the mouse cursor when you press the Ctrl key twice.

Make the mouse cursor larger and change the color

Having a large resolution on a small monitor can make it difficult to see the mouse cursor. I like to enlarge my cursor a bit, and change the color to make it stand out so it’s easier to see.

To adjust your mouse cursor settings, use the Start Menu to search for Mouse pointer size. There you can adjust the size and color of the mouse cursor.

Disable the Touchpad when using a mouse

When using Windows on a laptop without an external keyboard, I sometimes accidentally touch the touchpad while typing, which causes the cursor to jump around. To prevent this, I disable the touchpad when a mouse is connected.

To disable the touchpad when a mouse is connected:

1. Use the Start Menu to search for Touchpad settings.
2. Expand the Touchpad section.
3. Uncheck Leave touchpad on when a mouse is connected.

Change Touchpad triple-tap to middle-click

By default Windows opens the Windows search when you triple-tap the touchpad. That’s what the Windows key is for. Instead, I prefer to have the triple-tap act as a middle-click.

To change the touchpad triple-tap to middle-click:

1. In the touchpad settings window, expand the Three-finger gestures section.
2. Change the Taps dropdown to Middle mouse button.

Taskbar settings

The Windows taskbar has many settings that can be adjusted.

To open the taskbar settings window:

1. Right-click on the taskbar and choose Taskbar settings, or you can search the Start Menu for Taskbar settings.

Hide the search box from the taskbar

When I want to search, I use the Win key and start typing, so I don’t like the search box taking up space on the taskbar.

In the taskbar settings window, in the Taskbar items section, change the Search to Hide.

Hide the task view button

I don’t use multiple task views, and use Alt + Tab to switch between windows, so I hide the task view button. You can also use Win + Tab to open the task view.

In the taskbar settings window, in the Taskbar items section, toggle the Task view to Off.

Disable widgets

I don’t use the widgets on the taskbar and find them distracting, so I disable them.

In the taskbar settings window, in the Taskbar items section, toggle the Widgets to Off.

Decide which system tray icons to always show

The system tray is the area on the right side of the taskbar where you can see the time, volume, network status, and other system icons. There are some tray icons that I always want to see, and others that I don’t care about. You can control which ones are always shown, and which ones are hidden behind the Show hidden icons button to save space on the taskbar.

In the taskbar settings window, expand the Other system tray icons section, then toggle On the apps that you want to always show, and Off the ones to hide.

You can also simply drag-and-drop the system tray icons to/from the hidden area to control which ones are always shown.

Shift the Start Menu to the left

Windows 11 moved the Start Menu to the center of the taskbar by default. I prefer the previous Windows behaviour where it was on the left.

In the taskbar settings window, in the Taskbar behaviors section, change the Taskbar alignment to Left.

Never group taskbar buttons

I like to see all of my taskbar buttons including their labels, so I disable grouping them so it’s easy to see which ones are open and quickly select the one I want.

Here is a screenshot of the taskbar with the buttons combined:

And the same taskbar with the buttons not combined:

In the taskbar settings window, in the Taskbar behaviors section, change the Combine taskbar buttons and hide labels to Never.

Enable End Task on right-clicking taskbar icons

Typically when an application hangs, you need to open the Task Manager to kill the app. You can enable End Task in the right-click context menu of taskbar icons to make it easier to kill unresponsive apps.

To enable End Task on right-clicking taskbar icons, go to Settings > System > For developers and enable End Task.

Desktop settings

Change your desktop background image

By default Windows will often display a different desktop background image each day from Bing. I actually quite like this functionality for my personal computer, but prefer to have a static image on my work computer where I often do screen sharing. You may also want to adjust the desktop image if you remote desktop to other computers regularly, so that it’s easy to tell when you are working on your local computer or a remote one.

To change the desktop background image:

1. Right-click on the desktop and choose Personalize.
2. In the Personalization settings window, click on Background.
   1. You could also get here by searching the Start Menu for Background image settings.
3. In the Personalize your background section, choose Picture from the dropdown.
   1. If you want to cycle through multiple images, you can choose Slideshow instead.
4. Click the Browse button to select a picture or directory from your computer.
5. You may want to change the Choose a fit setting to Fill, Fit, or Stretch to make the image look better on your screen.

Turn transparency effects off

I don’t like transparency in my windows and menus, and you get a small performance boost by disabling it.

To disable transparency effects:

1. Right-click on the desktop and choose Personalize.
2. In the Personalization settings window, click on Colors.
3. Toggle the Transparency effects switch to Off.

Power settings

Don’t turn off the screen and go to sleep so fast

Windows will often turn the monitor off or put the computer to sleep after a short period of inactivity, such as 5 or 15 minutes depending on if it is on battery or not. I like to extend this time so that if I walk away from my computer for a little while, it’s less likely to be asleep when I come back.

To change the power settings:

1. Use the Start Menu to search for Power settings and open the Power, sleep, and battery settings.
2. Expand the Screen and sleep section if needed.
3. Adjust when the computer turns off the screen and goes to sleep to your liking.

Turn on enhanced performance power mode

In that same Power, sleep, and battery settings window, you can adjust the Power mode to prioritize performance over battery life and energy efficiency if you like.

Turn the computer off when I press the power button

By default, Windows will put the computer to sleep when you close the lid, or press the power button. I prefer to have the computer actually shut down when I press the power button. You may want your laptop to do nothing when the lid is closed, so it keeps running.

To change the power button and lid settings:

1. Use the Start Menu to search for Close lid and open the Change what closing the lid does option.
2. Adjust the When I close the lid and When I press the power button settings to your liking.
3. Click Save changes to apply the settings.

Windows features

Show multiple time zones in the taskbar clock

You can configure multiple time zones to show in the taskbar clock when you hover over it or click on it. This is great if you work with people in different time zones, travel frequently, or are a software developer and just want to know what the current UTC time is 😄.

To add additional time zones:

1. Right-click on the taskbar clock and choose Adjust date/time.
   1. You can also search the Start Menu for Date & time settings.
2. In the Date & time settings window, scroll down and click on the Additional clocks section.
3. The Date and Time window should open, allowing you to add up to 2 additional clocks and give them friendly names.

The result when hovering the mouse over the clock:

And when clicking on the clock:

Use the Windows Sandbox to test software and settings safely

Windows includes an app called Windows Sandbox. When you open the Windows Sandbox app, it creates a clean virtual environment that looks like a fresh install of Windows. Here you can experiment with software, settings, or files without affecting your main system, and when you close the app everything is erased. This is great for testing software or settings that you’re not sure about, without risking your main system. Just be sure not to save anything important in the Windows Sandbox, as it will be erased when you close it.

The Windows Sandbox app is not installed by default, so you may need to install it from the Windows Features:

1. Search the Start Menu for Windows Features, and choose Turn Windows features on or off.
2. In the Windows Features window, scroll down and enable Windows Sandbox.
3. Click OK to install it.
4. Restart your computer if prompted.

Now search for Windows Sandbox in the Start Menu to open the app.

Registry tweaks that don’t have a GUI setting

NOTE: Modifying the registry can be dangerous if you don’t know what you’re doing, so be sure to backup your registry before making any manual changes.

You can try the commands below in the Windows Sandbox first to see if you like the changes.

I provide terminal commands instead of manual point-and-click steps for modifying the registry to help ensure that only the intended keys are modified. You can run these commands in PowerShell or Command Prompt.

Some commands shown below may need to be ran from an elevated terminal (e.g. run PowerShell as an Administrator), otherwise you may get an error like Requested registry access is not allowed. Also, you may need to restart your computer for some changes to take effect.

If you are curious about the syntax of the registry commands, you can find the reg.exe MS docs here.

If you want to easily apply all of the registry tweaks below, simply download this .reg file and double-click it to run it.

Disable searching the web in the Start Menu search

When I search from the Start Menu, I want it to only search my local machine.

Here are screenshots before and after disabling the web search:

Run the following command to disable web search in the Start Menu:

reg.exe add "HKCU\SOFTWARE\Microsoft\Windows\CurrentVersion\Search" /v BingSearchEnabled /t REG_DWORD /d 0 /f

To revert back to the default behavior, run:

reg.exe delete "HKCU\SOFTWARE\Microsoft\Windows\CurrentVersion\Search" /v BingSearchEnabled /f

Note that it also disables Copilot, which may or may not be desired.

Always open “More options” context menu in Windows 11+

Windows 11 modified the right-click context menu to only show a few options by default, and you have to click “Show more options” to see the rest. I prefer the previous Windows behavior where all options are shown by default.

Below are screenshots of the context menu before and after running the command.

Default right-click context menu:

Right-click context menu with all options shown:

Run the following command to always show all options in the context menu:

reg.exe add "HKCU\Software\Classes\CLSID\{86ca1aa0-34aa-4e8b-a509-50c905bae2a2}\InprocServer32" /f /ve

To revert back to the default behavior, run:

reg.exe delete "HKCU\Software\Classes\CLSID\{86ca1aa0-34aa-4e8b-a509-50c905bae2a2}" /f

Source and more info

NOTE: Windows 11 updated to allow pressing Shift + Right-click to show all options in the context menu, so you may prefer to do that over using this registry tweak.

Speed up the right-click context menu

When you right-click a file or folder, Windows has an artificial delay of 400 milliseconds before showing the context menu.

Run the following command to change the delay to 50 milliseconds:

reg.exe add "HKCU\Control Panel\Desktop" /v MenuShowDelay /t REG_SZ /d 50 /f

To revert back to the default behavior, run:

reg.exe add "HKCU\Control Panel\Desktop" /v MenuShowDelay /t REG_SZ /d 400 /f

Also, before the context menu is shown, the Send to menu discovers all of the apps and connected devices you can send the file to before it actually shows the menu. We can change this so that it does not enumerate devices until you hover over the Send to menu.

Run the following command to delay Send To from looking for devices right away:

reg.exe add "HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\Explorer" /v DelaySendToMenuBuild /t REG_DWORD /d 1 /f

To revert back to the default behavior, run:

reg.exe delete "HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\Explorer" /v DelaySendToMenuBuild /f

Source and more info

Disable delay of startup apps

Windows puts a delay of 10 seconds before it starts launching apps in the Startup folder.

Run the following command to disable the startup apps delay:

reg.exe add "HKCU\SOFTWARE\Microsoft\Windows\CurrentVersion\Explorer\Serialize" /v Startupdelayinmsec /t REG_DWORD /d 0 /f

To revert back to the default behavior, run:

reg.exe delete "HKCU\SOFTWARE\Microsoft\Windows\CurrentVersion\Explorer\Serialize" /v Startupdelayinmsec /f

Source and more info

Bonus: Microsoft PowerToys

I was planning to keep this post to only native Windows features and settings, but I couldn’t resist including Microsoft PowerToys. PowerToys is kind of Microsoft’s way of quickly experimenting and iterating on features that should be in Windows, but aren’t. If a feature gets popular enough, it may be included in Windows natively.

Microsoft PowerToys is an application that adds a ton of great features to Windows, and it is being updated all the time.

See the Microsoft PowerToys docs for extensive documentation on all of the features, and how to install and configure them.

A few of my favourite features are:

• Always On Top: Keep a window always on top of others.
• Find My Mouse: Spotlight the mouse cursor when you press the Ctrl key twice.
• File Locksmith: Easily unlock files that are in use by other processes.
• Image Resizer: Resize images quickly and easily.
• Color Picker: Get the RGB, HEX, and HSL values of any color on the screen.

You can install PowerToys by running the following command in a terminal, such as PowerShell:

winget install --id Microsoft.PowerToys --source winget

Conclusion

I hope you found some of these settings and features helpful. Have a favourite or one that I didn’t mention? Let me know in the comments!

Happy customizing!

TL;DR

Here’s the PowerShell command to find the assembly version of a DLL file:

[System.Reflection.AssemblyName]::GetAssemblyName("C:\path\to\your.dll")

The object returned will contain many properties, with the assembly Version and Name written the to the terminal by default.

Since we are just calling a .NET method, you could also do this as C# code in a console app.

var assembly = System.Reflection.AssemblyName.GetAssemblyName("C:\\path\\to\\your.dll");
System.Console.WriteLine(assembly.Version);

Background

I was having a problem where the version of the System.Memory.dll assembly being copied to my application artifacts was different than the version referenced by my NuGet packages, causing my application to crash at runtime. NuGet automatically included an assembly binding redirect in my app.config file, but the version in the binding redirect was not the same as the version of the assembly being copied into the artifacts. The assembly binding redirects were referencing version 4.0.2.0, but the version of the assembly being copied into the artifacts was 4.0.1.2 (although I didn’t know this yet).

Here is the assembly binding redirect that was automatically added to my app.config file by NuGet:

<assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1">
  <dependentAssembly>
    <assemblyIdentity name="System.Memory" publicKeyToken="cc7b13ffcd2ddd51" culture="neutral" />
    <bindingRedirect oldVersion="0.0.0.0-4.0.2.0" newVersion="4.0.2.0" />
  </dependentAssembly>
</assemblyBinding>

Often times you can find the assembly version of a DLL by simply looking at the file properties in File Explorer, under the Details tab. However, in this case, neither version of the System.Memory.dll assemblies was showing their proper assembly version in the file properties.

You can see that the File version and Product version fields of the assemblies in the NuGet package and in the artifact are not showing the actual assembly version of the DLL; either 4.0.2.0 or 4.0.1.2.

So I could see that the assembly versions were different, but wasn’t sure what the actual assembly versions were in order to update the assembly binding redirect.

PowerShell to the rescue!

Now that I knew the actual assembly versions, I could update the assembly binding redirect in my app.config file to match the version of the assembly being copied into the artifacts. Specifically, newVersion="4.0.1.2.

<assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1">
  <dependentAssembly>
    <assemblyIdentity name="System.Memory" publicKeyToken="cc7b13ffcd2ddd51" culture="neutral" />
    <bindingRedirect oldVersion="0.0.0.0-4.0.2.0" newVersion="4.0.1.2" />
  </dependentAssembly>
</assemblyBinding>

This fixed the runtime crash and got everything back on track in time for my release.

A proper fix

While updating the assembly binding redirect to use the older version of the assembly fixed the issue, it’s kind of a hacky solution. If we update the NuGet package to a newer version, NuGet will automatically update the assembly binding redirect version and things will break again. A better solution would be to find out why the older version of the assembly was being copied into the artifacts and fix it.

I had already confirmed that all projects in the solution were referencing the same version of the System.Memory NuGet package, so I knew that wasn’t the issue. So I decided to build my projects and then use PowerShell to find all of the System.Memory.dll assemblies and report their assembly version.

Here is the PowerShell script I used:

# Find all System.Memory.dll assemblies in the repository.
[string] $directoryPath = 'C:\MyProjectRepo'
[string[]] $assemblyFilePaths =
  Get-ChildItem -Path $directoryPath -Recurse -Filter 'System.Memory.dll' |
  Select-Object -ExpandProperty FullName

# Get the assembly version of each assembly, and add the file path to the object.
$assemblies = @()
foreach ($filePath in $assemblyFilePaths)
{
  $assembly = [System.Reflection.AssemblyName]::GetAssemblyName($filePath)
  $assembly | Add-Member -MemberType NoteProperty -Name FilePath -Value $filePath
  $assemblies += $assembly
}

# Output the assembly versions and file paths, sorted by version then file path.
$assemblies | Select-Object Version, FilePath | Sort-Object Version, FilePath

The output of the script looked something like this:

Version FilePath
------- --------
4.0.1.2 C:\MyProjectRepo\Project1.Tests\bin\Debug\System.Memory.dll
4.0.1.2 C:\MyProjectRepo\Project2.Tests\bin\Debug\System.Memory.dll
4.0.1.2 C:\MyProjectRepo\Project3.Tests\bin\Debug\System.Memory.dll
...
4.0.2.0 C:\MyProjectRepo\Project1\bin\Debug\System.Memory.dll
4.0.2.0 C:\MyProjectRepo\Project2\bin\Debug\System.Memory.dll
4.0.2.0 C:\MyProjectRepo\Project3\bin\Debug\System.Memory.dll
...

You can see that all of the test projects were bringing in the older version of the assembly, while the main projects were bringing in the newer version. The test projects did not reference the System.Memory NuGet package, so when they needed the System.Memory.dll assembly they must have just been copying the older version from the GAC (Global Assembly Cache). Then somehow the assembly from one of the test projects was being copied into the artifacts; unfortunately, this particular solution has a non-standard build process.

The solution was to add a reference to the System.Memory NuGet package to each of the test projects that needed it so they would bring in the correct version of the assembly. I then reverted the change I had made to the assembly binding redirect in the app.config file, and now it can be automatically managed by NuGet again.

Conclusion

If you came here just wanting to know how to get the assembly version of a DLL file, I hope the TL;DR got you going quickly. If you read the entire post, I hope you found the background information helpful and maybe learned something new.

Happy coding!

Visual Studio 2022 v17.8 and NuGet 6.8 introduced a wonderful security feature that will generate warnings for NuGet packages that your projects reference that have known security vulnerabilities. Visual Studio v17.12 and NuGet v6.12 took this further by also generating warnings for vulnerable transitive dependencies those packages depend on (see the VS release notes). This gives developers better insight into potential security risks in their software, and can prompt them to update NuGet packages to a more secure version. Read more about the NuGet audit features on the MS docs here.

Here’s an example of a NuGet audit warning message for a package with a known vulnerability:

NU1904: Warning As Error: Package 'log4net' 2.0.8 has a known critical severity vulnerability, https://github.com/advisories/GHSA-2cwj-8chv-9pp9

The problem

NuGet generating warnings for security vulnerabilities in direct and transitive dependencies is great, but it can have an unintended side-effect of breaking the build if your projects are configured to treat warnings as errors. Treating warnings as errors is not on by default, but enabling it is a common practice to help ensure code quality and security.

This new NuGet audit feature means that if you have TreatWarningsAsErrors enabled, your code may no longer compile, even if you haven’t changed the code. Some examples of when this could happen include:

• You update Visual Studio / NuGet on your local machine to a version that generates new vulnerability warnings, so you can no longer build the code locally.
• Your build server updates Visual Studio / NuGet, so the build server can no longer build the code. Hosted platforms like GitHub and Azure DevOps agents often install new versions without any notice.
• A vulnerability is discovered in a NuGet package that your project uses and it is added to https://github.com/advisories/.

A common problem developers encounter sooner or later is when code compiles one day, but not the next, even though you haven’t changed the code. It can be very frustrating.

The solutions

There are a few ways to work around the problem of NuGet audit warnings breaking the build.

The best solution is to:

• Update your NuGet package reference to a version that doesn’t have a vulnerability.

While this is the simplest and best solution, it may not always be possible. A few reasons why include:

• The latest version of the NuGet package (or one of its dependencies) has a vulnerability.
• The NuGet package is no longer maintained, so there is no new version to update to.
• Newer versions of the NuGet package (or one of its dependencies) have a breaking change that would require significant code changes, and you do not have the time or resources to dedicate to making and testing those changes right now.

When updating the NuGet package is not a viable solution

If updating the NuGet package is not possible, there are a few other solutions you can try. These are listed in order of most recommended to least recommended:

• Do not treat NuGet audit warnings as errors by using WarningsNotAsErrors: This is the best solution, as it will allow your code to compile, and you will still be notified of the security vulnerabilities as a warning. See the MS docs here for how to enable or disable it

  • Add the following to your project file (.csproj) to treat the NuGet audit warnings as warnings instead of errors:

    <WarningsNotAsErrors>NU1901,NU1902,NU1903,NU1904</WarningsNotAsErrors>
    

    These are the 3 NuGet audit warning codes that I encountered, but there may be others.

    If you are editing the .csproj file by hand, you will want to add it to the <PropertyGroup> section of both your Debug and Release configurations.

    Here is a screenshot of modifying the project properties in Visual Studio to enable “Treat warnings as errors” and prevent NuGet audit warnings from being treated as errors (I forgot to add NU1901 in the screenshot):

    

• Suppress specific NuGet audit advisories: The next best solution is to ignore just the specific NuGet package advisory that you are not able to workaround. A potential downside is that because you will no longer get a warning, you may forget the package has a vulnerability. Here is an example of the code to add to your .csproj file to exclude the specific log4net advisory mentioned earlier:

  <Project Sdk="Microsoft.NET.Sdk">
    <!--  other parts of the project left out of this example -->
    <ItemGroup>
      <NuGetAuditSuppress Include="https://github.com/advisories/GHSA-2cwj-8chv-9pp9" />
    </ItemGroup>
  </Project>
  

  See the NuGet audit docs for more information.

• Disable TreatWarningsAsErrors: This is not ideal, as it will prevent you from being forced to fix code quality issues and security vulnerabilities, which some people and companies prefer. See the MS docs for how to enable or disable it
• Disable the NuGet audit feature: This is not recommended, as it will prevent you from being notified of security vulnerabilities. See the MS docs for how to disable it, or have it ignore transitive dependencies.

All of these solutions require making changes to the project file (.csproj). If you only have a few offending projects, updating each project file isn’t too troublesome. If you have 10s or 100s of projects though, it can be a pain to update them all.

A better solution is to leverage a Directory.Build.props file to apply the changes to all projects in a directory. You can read more about Directory.Build.props and how to use it on the MS docs here.

This MS doc has more information on some of the workarounds mentioned above.

You can find more information about potential actions to take when you encounter a vulnerable dependency in the NuGet audits docs here, and this MS blog post.

Conclusion

The NuGet audit feature is a great addition to help developers be aware of security vulnerabilities in their projects. However, it can have the unintended side-effect of breaking the build if you treat warnings as errors. By updating your NuGet packages to versions that do not have vulnerabilities, or by using one of the workarounds mentioned above, you can prevent the build from breaking and still be notified of security vulnerabilities in your projects.

I hope this article helps you keep your code compiling and secure. If you have any questions or comments, please leave them below.

Happy coding!

Below are some of the podcasts I enjoy, typically on Spotify at 1.8x speed, and why I like them.

Technical podcasts

I’m primarily a .NET developer, so the technical podcasts I listen to are usually .NET or Azure focused. Here are some technical podcasts that are great for software developers and IT pros:

• Azure DevOps Podcast: This podcast is hosted by Jeffrey Palermo, and is a great way to keep up-to-date with the latest .NET and Azure features and technology. He interviews a wide range of guests, such as Microsoft employees and MVPs, .NET-related authors, and other software developers in the industry, some of which have several decades of experience.
• The PowerShell Podcast: This podcast is hosted by Andrew Pla, and features guests from the PowerShell community. This podcast is a great way to stay up-to-date with what is happening in the PowerShell world, hear from others who use PowerShell regularly, and learn about new modules and tools that can help make IT pros and developers more productive.
• .NET Rocks: This podcast is hosted by Carl Franklin and Richard Campbell, and they interview guests from the .NET community. Carl and Richard have been podcasting for over 20 years, and have a wealth of knowledge and experience in the tech industry. They have interviewed many of the top names in the .NET community, and have a large back catalog of episodes that you can listen to.
• The Modern .NET Show: This podcast is hosted by Jamie Taylor, and he interviews guests from the .NET community. Jamie’s podcast is a great way to stay up-to-date with the latest .NET features and technology, and hear from others who are using .NET in their day-to-day work.
• Run As Radio: This podcast is hosted by Richard Campbell and has nearly 1000 episodes, with a new one each week. He interviews guests from the IT community on a wide range of topics, and is a great way to keep up-to-date with the latest trends and tools in the IT industry.

Some of these podcasts often provide discount codes for upcoming conferences, which can save you hundreds of dollars off registration.

Non-technical podcasts

This is a list of non-technical podcasts that your spouse or even your kids might enjoy, where you don’t need to be a software developer or IT pro to understand what they are talking about or find it interesting:

Interesting true stories:

• Corecursive: This podcast is hosted by Adam Gordon Bell. Adam will either have a guest on the show to tell their story, or sometimes he will just tell someone’s story himself, of doing something notable in the tech industry, such as creating the JSON spec, porting Doom to a gaming console, or shadow-working on the Apple campus without them knowing or getting paid in hopes of shipping their software with the Mac OS. I really like this podcast, as it is essentially a collection of interesting true stories about people who have done something in the tech industry. The stories may have happened 50 years ago or 5 years ago, and they are all interesting and well told. It is a great way to hear stories from other software developers and get a history of what has changed over the years, and to learn about the different paths people have taken to get into the tech industry.
• Darknet Diaries: This podcast is hosted by Jack Rhysider, and is a collection of true stories about hackers, malware, and cyber security. Like the Corecursive podcast, it focuses on telling true stories, but about anything related to cyber security or the darker side of the web, such as the story of the guy who hacked the FBI, or the judge who spent months/years posing online as a terrorist in order to gain intel and alert the authorities before a terrorist plan could be executed.
• The Pragmatic Engineer: This podcast is hosted by Gergely Orosz. Gergely typically interviews a guest on the show where they talk about the history of a company, product, or technology, such as how Microsoft evolved over the years from the 1980s to today, or how GitHub got started and has grown and changed over time.

Level-up your engineering soft skills:

• Soft Skills Engineering: This podcast is hosted by Dave Smith and Jamison Dance, and is a great way to get career advice and hear stories from other software developers. The hosts read questions submitted by listeners, such as how to ask for a promotion, deal with a difficult coworker, or get your voice heard in the company, and then give their advice on how to handle the situation. You can submit your own questions for them on their website.
• Developing Up: This podcast is no longer recoding new episodes, but still has a lot of great advice nonetheless. Like the Soft Skills Engineering podcast, Developing Up discusses many of the processes around being a software engineer (code reviews, pair programming, security, working remotely, career advice) that remain true over time.

Other podcasts:

• Hanselminutes: This podcast is hosted by Scott Hanselman, and features guests from the tech and other industries. Sometimes Scott’s podcasts are very technical, and other times not at all. Compared to the other podcasts on this list, I would say Scott’s podcast is a variety show, and you’re never quite sure what you’re going to get. Due to the nature of so many different topics, I find some episodes more interesting than others.
• Compromising Positions: This podcast is hosted by Lianne Potter and Jeff Watkins, and is all about cyber security. They typically interview a non-technical guest on their show and discuss how security could be improved in their area. I personally find this podcast hit or miss; I’ve really enjoyed some episodes, while others left me zoning out or feeling bored.

Conclusion

I plan to add to this list over time as I discover more great tech-related podcasts, so check back later for more recommendations.

For now, I hope you find this list helpful and are able to discover a new podcast that you love.

Happy listening! 🎧

NOTE: Only the System.Data.SqlClient NuGet package is deprecated, not the System.Data.SqlClient namespace in .NET Framework. This means it only affects .NET Core apps, not .NET Framework apps. That said, .NET Framework apps can still benefit from using Microsoft.Data.SqlClient instead, as that’s where development is happening for new features and performance improvements.

TL;DR

The SqlClient GitHub repo has a migration cheat sheet for everything that you will need to change when migrating from System.Data.SqlClient to Microsoft.Data.SqlClient.

The team also plans to automate much of the migration process with the .NET Upgrade Assistant in the future, so keep an eye out for that.

My journey

Microsoft.Data.SqlClient was introduced in 2019, and skimming the GitHub migration guide issue said to simply:

• Add the Microsoft.Data.SqlClient NuGet package to your project and
• Replace using System.Data.SqlClient; with using Microsoft.Data.SqlClient;

That seemed simple enough.

So I did that, and everything compiled fine. Nice! 💪

However, I then ran the integration tests and saw a lot of failures 😭.

NOTE: Be weary of runtime issues after migrating. Be sure to test your application.

Issue 1: Connection error

The first error I encountered was an issue connecting to the SQL database:

A connection was successfully established with the server, but then an error occurred during the login process.
(provider: SSL Provider, error: 0 - The certificate chain was issued by an authority that is not trusted.)

Microsoft.Data.SqlClient is meant to be a backward compatible improvement over System.Data.SqlClient, and that includes being more secure. All connections are now encrypted by default, and the server’s certificate must be trusted. If you are connecting to a SQL Server that is using a self-signed certificate, you will need to add the certificate to the trusted root certificate store on the machine running the application, or (not recommended) adjust the connection string to either use Encrypt=False or TrustServerCertificate=True.

Issue 2: Additional namespaces to change

The next error I ran into was:

Failed to convert parameter value from a SqlDataRecord[] to a IEnumerable`1.
unhandled_exception_InvalidCastException

After a few hours of unravelling and debugging the app, I came across this comment on a GitHub issue mentioning that in addition to updating the using System.Data.SqlClient; statements, I also needed to update the using Microsoft.SqlServer.Server; statements to using Microsoft.Data.SqlClient.Server;. I also found this Stack Overflow answer that mentioned the same thing.

Issue 3: Connection string formatting

The final problem I ran into was some of the unit tests compared the SQL connection string to ensure it had all of the expected properties and values. It seems that the SqlConnectionStringBuilder.ConnectionString property in Microsoft.Data.SqlClient changed the formatting to use spaces in the connection string properties, so ApplicationIntent becomes Application Intent, and MultiSubnetFailover becomes Multi Subnet Failover. It’s a breaking change that most likely won’t affect your app, unless your app is used to build or return connection strings for other apps.

The problem is that the System.Data.SqlClient Connection String does not support the spaces, but the Microsoft.Data.SqlClient Connection String does. So if an app using System.Data.SqlClient tries to connect using a connection string provided by Microsoft.Data.SqlClient, it will fail with an error message like the following:

Keyword not supported: 'application intent'

Your options here are to either update all of your apps to use Microsoft.Data.SqlClient, or put code in place to ensure spaces are removed from the connection string keywords.

I opened this GitHub issue to see if MS will consider using the backward-compatible keywords, and created this PR to update the migration cheat sheet (mentioned below) with this problem.

Conclusion

After making these changes, everything worked as expected 🙌.

Later I noticed I had overlooked this migration cheat sheet that was linked to from the deprecation announcement page 🤦‍♂️. It includes the first two changes I mentioned above, as well as a few others that I didn’t run into. The deprecation announcement page also mentions they plan to update the .NET Upgrade Assistant to help with this migration in the future, so by the time you read this, you may be able to use that tool.

If you need to migrate your apps, I hope you find this useful.

Happy coding!

Just like you might define an alias for a function, you can define an alias for a .NET class or enum type, only it’s called a “type accelerator”. It turns out that I (and probably you) had been using them all along without realizing it.

Built-in type accelerators

Here are some common built-in type accelerators:

[int] # Instead of [System.Int32]
[string] # Instead of [System.String]
[bool] # Instead of [System.Boolean]
[datetime] # Instead of [System.DateTime]
[array] # Instead of [System.Array]
[hashtable] # Instead of [System.Collections.Hashtable]
[xml] # Instead of [System.Xml.XmlDocument]
[regex] # Instead of [System.Text.RegularExpressions.Regex]
[pscredential] # Instead of [System.Management.Automation.PSCredential]
[pscustomobject] # Instead of [System.Management.Automation.PSCustomObject]
[ipaddress] # Instead of [System.Net.IPAddress]

So the following two lines are equivalent:

[int] $myInt = 5
[System.Int32] $myInt = 5

And these two lines are equivalent:

[string]::IsNullOrWhitespace($myString)
[System.String]::IsNullOrWhitespace($myString)

And these two lines are equivalent:

[pscredential] $myCred = Get-Credential
[System.Management.Automation.PSCredential] $myCred = Get-Credential

And these two lines are equivalent:

[pscustomobject] $myObject = @{ Name = 'John'; Age = 30 }
[System.Management.Automation.PSCustomObject] $myObject = @{ Name = 'John'; Age = 30 }

Basically, type accelerators are just an alias for a fully qualified .NET type name. The first two examples don’t save too many keystrokes, but ones like [pscredential] instead of remembering System.Management.Automation.PSCredential can be a real time saver.

Before understanding that they are simply an alias, I would do a Google lookup for the full type name every time I needed to use a non-common one, to make sure it would work on not only my machine, but others’ as well. Knowing that they are aliases built into the language gives me confidence to use them in my scripts, regardless of the machine they’re run on.

Be sure to check out the full list of built-in type accelerators in the MS docs, as there are quite a few.

Get all type accelerators

You can get a list of all of the built-in type accelerators for your PowerShell version by running the following command:

[PSObject].Assembly.GetType('System.Management.Automation.TypeAccelerators')::Get

This is similar to running Get-Alias to get a list of all cmdlet aliases, only these are for class/enum types.

Custom type accelerators

You can also create your own type accelerators, whether for your own classes/enums, or for .NET classes that don’t have built-in aliases.

Here’s an example of creating a type accelerator for the System.Net.Http.HttpClient class:

$accelerator = [PSObject].Assembly.GetType('System.Management.Automation.TypeAccelerators')
$accelerator::Add('HttpClient', 'System.Net.Http.HttpClient')

Now you can use [HttpClient] instead of [System.Net.Http.HttpClient] in your scripts, like this:

[HttpClient] $client = New-Object HttpClient

Beware that custom type accelerators only apply if they’re included in the script or module that defines them; they are not available globally like the built-in ones. This means that if you defined a custom type accelerator in one script, it may not be available in another script. Similarly, if you define a custom type accelerator in your $Profile, it will be available on your local machine, but may not be available if the script is run on a different machine.

Type accelerators in modules

If you’re creating a module and want to include a custom type accelerator for your module’s class/enum so it can be easily referenced, you can include the type accelerator definition in your module’s .psm1 file. See the MS documentation for more details.

Using namespaces instead of type accelerators

Rather than creating a bunch of custom type accelerators for .NET types that don’t have built-in ones, you can instead use the using namespace statement to import an entire namespace and then use the types in that namespace without needing the fully qualified name.

Here’s an example of using the using namespace statement to import the System.Net.Http namespace and then using the HttpClient and HttpRequestHeaders classes without the fully qualified name:

using namespace System.Net.Http

$myHttpClient = [HttpClient]::new() # Instead of [System.Net.Http.HttpClient]::new()
$headers = [HttpRequestHeaders]::new() # Instead of [System.Net.Http.Headers.HttpRequestHeaders]::new()

A common one that I find myself using is:

using namespace System.IO

$myFileContents = [File]::ReadAllText('C:\path\to\file.txt') # Instead of [System.IO.File]::ReadAllText('C:\path\to\file.txt')

This is a great alternative to using .NET types without having to type out their fully qualified name every time, or define a custom type accelerator for them.

Conclusion

Type accelerators are a great way to save keystrokes. There are built-in aliases for many .NET types, and you can create your own custom type accelerators as well. If you find yourself using a .NET type often, consider using it’s type accelerator, or including a using namespace statement to import it’s namespace. Just remember that if you include a custom type accelerator or namespace in your $Profile, it may not be available on other machines. For more information and examples of using type accelerators, check out this awesome blog post by 4syspos.

Happy scripting!

You can see that in addition to the typical whitespace settings, it also lists many language-specific settings as well, allowing everyone on your team to have consistent settings for the repository. There are too many settings to fit them all in the screenshots, and new ones are periodically added with new versions of C#, .NET, and other languages.

The GUI is great for quickly seeing all of the available settings and their possible values. You can still view the .editorconfig file’s plain text by using the View.ViewCode shortcut (F7).

One thing I don’t particularly like is that as soon as you open the file in the GUI editor, it automatically adds every setting to the text file. This balloons my typical ~10 line .editorconfig file to around 100 lines. I would prefer it if it only added settings that were changed from their default value (like how VS Code does with it’s settings.json file), but since it’s a file that typically isn’t viewed or changed often, it’s not too big of a deal.

The EditorConfig GUI is available in Visual Studio 2022 (and possibly earlier versions, but I’m not sure). You can read more about the EditorConfig support in Visual Studio in the official documentation.

I hope you found this useful. Happy coding!

TL;DR

This post shows how you can build a PowerShell function to easily retry any PowerShell code that produces a terminating or non-terminating error. If you want to skip the explanation and evolution of the code, jump to the bottom of this post to see the final function and examples, or view them on my GitHub gist here.

Traditional retry logic

Here’s the traditional way that you might write some code with retry logic:

[int] $maxNumberOfAttempts = 5
[int] $numberOfAttempts = 0
while ($true) {
  try {
    Do-Something
    break # Break out of the while-loop since the command succeeded.
  } catch {
    $numberOfAttempts++

    if ($numberOfAttempts -ge $maxNumberOfAttempts) {
      throw
    }

    Start-Sleep -Seconds 3
  }
}

You can see that the code above will attempt to perform the Do-Something command up to 5 times, waiting 3 seconds between each attempt. If all 5 attempts fail, it will throw the exception.

The basic concept of a retry function

Now suppose later in your code you need to call Do-AnotherThing, and then Do-SomeOtherThing, and you wanted retry logic for those as well. Rather than repeating all of the above code, we can wrap it in a function and pass in the ScriptBlock to execute.

Here is what the function might look like:

function Invoke-ScriptBlockWithRetries {
  param
  (
    [scriptblock] $ScriptBlock,
    [int] $MaxNumberOfAttempts = 5
  )

  [int] $numberOfAttempts = 0
  while ($true) {
    try {
      Invoke-Command -ScriptBlock $ScriptBlock
      break # Break out of the while-loop since the command succeeded.
    } catch {
      $numberOfAttempts++

      if ($numberOfAttempts -ge $MaxNumberOfAttempts) {
        throw
      }

      Start-Sleep -Seconds 3
    }
  }
}

You can see that the code is pretty much identical, except the function takes in the ScriptBlock to execute and the maximum number of attempts as parameters, and instead of calling Do-Something directly, we use Invoke-Command to execute the ScriptBlock.

With this function defined, we can now execute our commands, with retries, like this:

# Use positional parameters and the default maximum number of attempts.
Invoke-ScriptBlockWithRetries { Do-Something }

# Use named parameters and specify the maximum number of attempts.
Invoke-ScriptBlockWithRetries -ScriptBlock { Do-AnotherThing } -MaxNumberOfAttempts 10

# You can also capture the output of the script block.
$resultOfDoSomeOtherThing = Invoke-ScriptBlockWithRetries -ScriptBlock { Do-SomeOtherThing }

# The script block can contain multiple lines of code, and can be defined as a variable.
[scriptblock] $action = {
  [string] $fileLocation = "C:\temp\file.txt"
  [string] $fileContents = Get-Content -Path $fileLocation
  [string] $newFileLocation = "C:\temp\newfile.txt"
  [string] $newFileContents = $fileContents -replace "old", "new"
  Set-Content -Path $newFileLocation -Value $newFileContents
  Write-Output "Successfully replaced 'old' with 'new' in file '$fileLocation' and saved it to '$newFileLocation'."
}
Invoke-ScriptBlockWithRetries -ScriptBlock $action -MaxNumberOfAttempts 3

Retrying non-terminating errors too

You may have noticed a potential problem with our Invoke-ScriptBlockWithRetries function. It will only retry terminating errors; that is, exceptions that are thrown, but not non-terminating errors, such as Write-Error when the error action is Continue (the default).

On potential solution is to convert all non-terminating errors to terminating errors by using the $ErrorActionPreference variable at the start of your script:

$ErrorActionPreference = "Stop"

This will affect the entire script though, and is likely not what you want. Another alternative is to use the -ErrorAction parameter of the specific cmdlets that might produce non-terminating errors. In our previous example, you could do this:

Set-Content -Path $newFileLocation -Value $newFileContents -ErrorAction Stop

This would ensure that any errors written by the Set-Content cmdlet would be treated as terminating errors (e.g. thrown exceptions) and would get retried. Having to add -ErrorAction Stop to every cmdlet is tedious and error prone though.

A better way we can address this is to add a check for non-terminating errors and throw them if they occur, by making use of the -ErrorVariable parameter on our Invoke-Command:

function Invoke-ScriptBlockWithRetries {
  param
  (
    [scriptblock] $ScriptBlock,
    [int] $MaxNumberOfAttempts = 5
  )

  [int] $numberOfAttempts = 0
  while ($true) {
    try {
      Invoke-Command -ScriptBlock $ScriptBlock -ErrorVariable nonTerminatingErrors

      # Check for non-terminating errors and throw them so they get retried.
      if ($nonTerminatingErrors) {
        throw $nonTerminatingErrors
      }

      break # Break out of the while-loop since the command succeeded.
    } catch {
      $numberOfAttempts++

      if ($numberOfAttempts -ge $MaxNumberOfAttempts) {
        throw
      }

      Start-Sleep -Seconds 3
    }
  }
}

Now both terminating and non-terminating errors will be retried 🙂

Making the function more flexible

Now that we have a nice reusable function, let’s improve it to make it more flexible and use parameter validation. We can add parameters so the user can configure how long to wait between retries, whether to use exponential backoff, provide a list of errors that should not be retried, and whether to retry non-terminating errors or not:

function Invoke-ScriptBlockWithRetries {
  [CmdletBinding()]
  param (
    [Parameter(Mandatory = $true, HelpMessage = "The script block to execute.")]
    [ValidateNotNull()]
    [scriptblock] $ScriptBlock,

    [Parameter(Mandatory = $false, HelpMessage = "The maximum number of times to attempt the script block when it returns an error.")]
    [ValidateRange(1, [int]::MaxValue)]
    [int] $MaxNumberOfAttempts = 5,

    [Parameter(Mandatory = $false, HelpMessage = "The number of milliseconds to wait between retry attempts.")]
    [ValidateRange(1, [int]::MaxValue)]
    [int] $MillisecondsToWaitBetweenAttempts = 3000,

    [Parameter(Mandatory = $false, HelpMessage = "If true, the number of milliseconds to wait between retry attempts will be multiplied by the number of attempts.")]
    [switch] $ExponentialBackoff = $false,

    [Parameter(Mandatory = $false, HelpMessage = "List of error messages that should not be retried. If the error message contains one of these strings, the script block will not be retried.")]
    [ValidateNotNull()]
    [string[]] $ErrorsToNotRetry = @(),

    [Parameter(Mandatory = $false, HelpMessage = "If true, only terminating errors (e.g. thrown exceptions) will cause the script block will be retried. By default, non-terminating errors will also trigger the script block to be retried.")]
    [switch] $DoNotRetryNonTerminatingErrors = $false
  )

  [int] $numberOfAttempts = 0
  while ($true) {
    try {
      Invoke-Command -ScriptBlock $ScriptBlock -ErrorVariable nonTerminatingErrors

      if ($nonTerminatingErrors -and (-not $DoNotRetryNonTerminatingErrors)) {
        throw $nonTerminatingErrors
      }

      break # Break out of the while-loop since the command succeeded.
    } catch {
      $numberOfAttempts++

      [string] $errorMessage = $_.Exception.ToString()
      [string] $errorDetails = $_.ErrorDetails
      Write-Verbose "Attempt number '$numberOfAttempts' of '$MaxNumberOfAttempts' failed.`nError: $errorMessage `nErrorDetails: $errorDetails"

      if ($numberOfAttempts -ge $MaxNumberOfAttempts) {
        throw
      }

      # If the errorMessage contains one of the errors that should not be retried, then throw the error.
      foreach ($errorToNotRetry in $ErrorsToNotRetry) {
        if ($errorMessage -like "*$errorToNotRetry*" -or $errorDetails -like "*$errorToNotRetry*") {
          Write-Verbose "The string '$errorToNotRetry' was found in the error message, so not retrying."
          throw
        }
      }

      [int] $millisecondsToWait = $MillisecondsToWaitBetweenAttempts
      if ($ExponentialBackoff) {
        $millisecondsToWait = $MillisecondsToWaitBetweenAttempts * $numberOfAttempts
      }
      Write-Verbose "Waiting '$millisecondsToWait' milliseconds before next attempt."
      Start-Sleep -Milliseconds $millisecondsToWait
    }
  }
}

Here is a contrived example of how you might use the updated function:

# Simulate some code that might fail in various ways.
[scriptblock] $flakyAction = {
  $random = Get-Random -Minimum 0 -Maximum 10
  if ($random -lt 2) {
    Write-Output "Success"
  } elseif ($random -lt 4) {
    Write-Error "Error"
  } elseif ($random -lt 6) {
    Write-Error "Error DoNotRetry"
  } elseif ($random -lt 8) {
    throw "Exception"
  } else {
    throw "Exception DoNotRetry"
  }
}

# Call our scriptblock, ensuring any exceptions or errors containing "DoNotRetry" are not retried, but all others are.
# Use the -Verbose parameter to see additional details about any failures.
Invoke-ScriptBlockWithRetries -ScriptBlock $flakyAction -MaxNumberOfAttempts 10 -MillisecondsToWaitBetweenAttempts 100 -ExponentialBackoff -ErrorsToNotRetry "DoNotRetry" -Verbose

And here is the output you might see when running the above code, where it first fails with an exception, and then fails with an error, and succeeds on the 3rd attempt:

VERBOSE: Attempt number '1' of '10' failed.
Error: System.Management.Automation.RuntimeException: Exception
ErrorDetails:
VERBOSE: Waiting '100' milliseconds before next attempt.
Invoke-ScriptBlockWithRetries: C:\dev\Git\iQ\RQ.ClientCancellationProcess\Test.ps1:89:1
Line |
  89 |  Invoke-ScriptBlockWithRetries -ScriptBlock $flakyAction -MaxNumberOfA …
     |  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     | Error
VERBOSE: Attempt number '2' of '10' failed.
Error: System.Management.Automation.RuntimeException: Error
ErrorDetails:
VERBOSE: Waiting '200' milliseconds before next attempt.
Success

If you do not want non-terminating errors to be retried (e.g. the Write-Error cases in the $flakyAction above), provide the -DoNotRetryNonTerminatingErrors switch parameter.

You may have noticed that the verbose output includes the error message and error details. This is because some cmdlets, such as Invoke-WebRequest, sometimes put the error message in the ErrorDetails property.

More examples

Here are some more practical examples:

Example 1: Stop a service if it exists

This will only retry if the service “SomeService” exists. If it doesn’t, the error message “Cannot find any service with service name ‘SomeService’.” would be returned and the function won’t bother retrying.

Invoke-ScriptBlockWithRetries { Stop-Service -Name "SomeService" } -ErrorsToNotRetry 'Cannot find any service with service name'

Example 2: Validate a web request was successful

[scriptblock] $exampleThatReturnsData = {
  Invoke-WebRequest -Uri 'https://google.com'
}
$result = Invoke-ScriptBlockWithRetries -ScriptBlock $exampleThatReturnsData -MaxNumberOfAttempts 3

if ($result.StatusCode -eq 200) {
  Write-Output "Success"
}

Note: PowerShell 6+ have built-in Retry parameters on the Invoke-WebRequest and Invoke-RestMethod cmdlets that could be used instead.

Example 3: Dealing with failures

If you want to take additional actions on failures that still occur after all of the retries, you can catch the exception and handle it as needed.

[string] $nonExistentWebAddress = 'https://SomeAddressThatDoesNotExist.com'

[scriptblock] $exampleThatWillAlwaysFail = {
  Invoke-WebRequest -Uri $nonExistentWebAddress
}

try {
  Invoke-ScriptBlockWithRetries -ScriptBlock $exampleThatWillAlwaysFail -MillisecondsToWaitBetweenAttempts 100
} catch {
  $exceptionMessage = $_.Exception.Message
  Write-Error "An error occurred calling '$nonExistentWebAddress': $exceptionMessage"
  throw
}

Example 4: Do not retry expected errors

There may be certain errors that are expected in certain situations, or where you know a retry will not help. To save time, specify not to retry on these errors:

[scriptblock] $exampleThatReturnsData = {
  Invoke-RestMethod -Uri 'https://api.google.com'
}

[string[]] $noRetryMessages = @(
  '400 (Bad Request)'
  '401 (Unauthorized)'
  '404 (Not Found)'
)

Invoke-ScriptBlockWithRetries -ScriptBlock $exampleThatReturnsData -ErrorsToNotRetry $noRetryMessages

Example 5: Perform multiple actions

Because we use a scriptblock, we can perform multiple actions and if any of them fail, the entire scriptblock will be retried:

[scripblock] $getDataAndWriteItToAFileAndSendSlackMessage = {
  [string] $data = Invoke-RestMethod -Uri 'https://SomeApi.com/data'
  $data | Set-Content -Path 'C:\temp\data.txt'
  Send-SlackMessage -Message "Data was successfully retrieved and saved to 'C:\temp\data.txt'." -Channel '#general'
}

Invoke-ScriptBlockWithRetries -ScriptBlock $getDataAndWriteItToAFileAndSendSlackMessage

Final version of the function

One caveat with the above implementation is that non-terminating errors will be thrown as terminating errors if they are still failing after all of the retries, which may not be the desired behavior. I typically prefer to have all persisting errors thrown, as it allows for a single way to handle any errors produced by the script block (i.e. with a try-catch block).

For those that do not want this behaviour, I offer this final implementation that is not quite as straightforward, but provides an additional DoNotThrowNonTerminatingErrors parameter that allows for non-terminating errors to not be thrown if they are still failing after all of the retries:

function Invoke-ScriptBlockWithRetries {
  [CmdletBinding(DefaultParameterSetName = 'RetryNonTerminatingErrors')]
  param (
    [Parameter(Mandatory = $true, HelpMessage = "The script block to execute.")]
    [ValidateNotNull()]
    [scriptblock] $ScriptBlock,

    [Parameter(Mandatory = $false, HelpMessage = "The maximum number of times to attempt the script block when it returns an error.")]
    [ValidateRange(1, [int]::MaxValue)]
    [int] $MaxNumberOfAttempts = 5,

    [Parameter(Mandatory = $false, HelpMessage = "The number of milliseconds to wait between retry attempts.")]
    [ValidateRange(1, [int]::MaxValue)]
    [int] $MillisecondsToWaitBetweenAttempts = 3000,

    [Parameter(Mandatory = $false, HelpMessage = "If true, the number of milliseconds to wait between retry attempts will be multiplied by the number of attempts.")]
    [switch] $ExponentialBackoff = $false,

    [Parameter(Mandatory = $false, HelpMessage = "List of error messages that should not be retried. If the error message contains one of these strings, the script block will not be retried.")]
    [ValidateNotNull()]
    [string[]] $ErrorsToNotRetry = @(),

    [Parameter(Mandatory = $false, ParameterSetName = 'IgnoreNonTerminatingErrors', HelpMessage = "If true, only terminating errors (e.g. thrown exceptions) will cause the script block will be retried. By default, non-terminating errors will also trigger the script block to be retried.")]
    [switch] $DoNotRetryNonTerminatingErrors = $false,

    [Parameter(Mandatory = $false, ParameterSetName = 'RetryNonTerminatingErrors', HelpMessage = "If true, any non-terminating errors that occur on the final retry attempt will not be thrown as a terminating error.")]
    [switch] $DoNotThrowNonTerminatingErrors = $false
  )

  [int] $numberOfAttempts = 0
  while ($true) {
    try {
      Invoke-Command -ScriptBlock $ScriptBlock -ErrorVariable nonTerminatingErrors

      if ($nonTerminatingErrors -and (-not $DoNotRetryNonTerminatingErrors)) {
        throw $nonTerminatingErrors
      }

      break # Break out of the while-loop since the command succeeded.
    } catch {
      [bool] $shouldRetry = $true
      $numberOfAttempts++

      [string] $errorMessage = $_.Exception.ToString()
      [string] $errorDetails = $_.ErrorDetails
      Write-Verbose "Attempt number '$numberOfAttempts' of '$MaxNumberOfAttempts' failed.`nError: $errorMessage `nErrorDetails: $errorDetails"

      if ($numberOfAttempts -ge $MaxNumberOfAttempts) {
        $shouldRetry = $false
      }

      if ($shouldRetry) {
        # If the errorMessage contains one of the errors that should not be retried, then do not retry.
        foreach ($errorToNotRetry in $ErrorsToNotRetry) {
          if ($errorMessage -like "*$errorToNotRetry*" -or $errorDetails -like "*$errorToNotRetry*") {
            Write-Verbose "The string '$errorToNotRetry' was found in the error message, so not retrying."
            $shouldRetry = $false
            break # Break out of the foreach-loop since we found a match.
          }
        }
      }

      if (-not $shouldRetry) {
        [bool] $isNonTerminatingError = $_.TargetObject -is [System.Collections.ArrayList]
        if ($isNonTerminatingError -and $DoNotThrowNonTerminatingErrors) {
          break # Just break out of the while-loop since the error was already written to the error stream.
        } else {
          throw # Throw the error so it's obvious one occurred.
        }
      }

      [int] $millisecondsToWait = $MillisecondsToWaitBetweenAttempts
      if ($ExponentialBackoff) {
        $millisecondsToWait = $MillisecondsToWaitBetweenAttempts * $numberOfAttempts
      }
      Write-Verbose "Waiting '$millisecondsToWait' milliseconds before next attempt."
      Start-Sleep -Milliseconds $millisecondsToWait
    }
  }
}

You can also find this implementation and examples on my GitHub gist here.

Conclusion

By using a function like Invoke-ScriptBlockWithRetries, you can make your scripts more resilient to failures and avoid repeating the same retry logic over and over.

This is a function that I use in many of my scripts. Feel free to use it as-is, or update it to suit your needs. Have feedback or suggestions? Let me know by leaving a comment below.

Happy coding!

For a consistent way to access many settings and apps regardless of your Windows version, you can use a command prompt or the Run dialog box.

Opening the Run dialog box

There are two main ways to open the Run dialog box:

1. Press Win + R on your keyboard, or
2. Press Win to open the Start menu, type Run, and press Enter.

The Run dialog box will look something like this:

Opening a command prompt

Alternatively, you can open a command prompt, such as cmd or PowerShell. Here are two ways to do that:

1. Press Win + X to open the Windows X menu, then i to open PowerShell (use A instead to open a PowerShell Admin console).
2. Press Win to open the Start menu, type cmd or PowerShell, and press Enter.

Common Run commands

With either a command prompt or the Run dialog box open, type in one of the following commands and press Enter to open the corresponding Windows setting or app.

Note: If using a command prompt, it may need to be running As Admin to open some of these settings windows. A few commands only work from the Run dialog box and are marked as (Run only).

This blog article was inspired by this LinkedIn post which shows how to define many of these in a PowerShell function that can be used to search for the command you want.

Conclusion

I hope you find this list of commands useful. If you have any other commands that you find valuable, please share them in the comments below and I might add them to this list. I intend to keep this list updated as I discover more useful commands.

If you liked this post, you might also like my Handy Windows Command Prompt commands post.

Happy running!

Allman and One True Brace Style (OTBS)

Before diving into PowerShell over a decade ago, I was primarily a C# developer. The typical convention for C# has been to use the Allman indentation style for code. I love the Allman style. To me, it’s clean and makes code easier to read. Here’s an example of the Allman style:

function ReplaceDogWithCat ([string[]] $textToPrint)
{
    foreach ($text in $textToPrint)
    {
        if ($text -eq 'dog')
        {
            Write-Output 'cat'
        }
        else
        {
            Write-Output $text
        }
    }
}

If you’ve looked at open source PowerShell code, you’ve probably noticed that many people use the One True Brace Style (OTBS) for brace styling. Here’s the same example formatted using the OTBS style:

function ReplaceDogWithCat ([string[]] $textToPrint) {
    foreach ($text in $textToPrint) {
        if ($text -eq 'dog') {
            Write-Output 'cat'
        } else {
            Write-Output $text
        }
    }
}

Most fans of OTBS think that the Allman style wastes too much vertical space by putting the opening brace on a new line. To me though, that whitespace makes the code easier to read; it visually segregates the blocks of code allowing my mind to more easily focus on a single block.

When I look at the OTBS example above, my mind initially just sees one big block of text, rather than 4 distinct parts (function, foreach, if, else). Maybe it’s because I’ve been using Allman for so long, but the compactness of OTBS makes it feel cluttered to me.

Why use OTBS for PowerShell?

So if I love Allman style, why did I switch to OTBS for PowerShell?

There are two main reasons:

1. OTBS is more popular in the PowerShell community.
2. PowerShell has some restrictions that force the opening brace to be on the same line in some scenarios.

Popularity

Regardless of what style you prefer, you should use it consistently. If you’re working on a team, it’s best to agree on a common style and stick to it, otherwise you’ll end up with a mix of styles in your files, which can be a bit jarring and lead to confusion.

That said, it’s often best to try and use the most popular style. It means that when others need to work on your scripts, or when you bring new members onto your team, they’re more likely to be familiar with the style you’re using. They won’t have to spend time trying to understand the style you’re using, or updating their editor settings to match your style.

While I don’t have any hard proof that OTBS is the most popular, it’s what I’ve personally seen most often in open source projects. Also, it’s by far the most up-voted style on Joel Bennett’s GitHub discussion on the subject, which is linked to from the VS Code settings.

PowerShell restrictions

I’ve been using Allman style for PowerShell for over a decade. In the beginning I stumbled a bit, as there are a few scenarios that require the opening brace to be on the same line. The main examples are any cmdlet that uses a script block, such as ForEach-Object, Where-Object, Invoke-Command, etc. Many statements work fine with the opening brace on a new line though.

Here are some code examples to illustrate the issue:

# WORKS: The opening brace on a new line works fine for `foreach` loops.
foreach ($number in 1..10)
{
    $number
}

# WORKS: It works fine for `if` and `switch` statements too.
if ($number -gt 5)
{
    $number
}

# FAILS: This will halt execution to prompt for a script block.
1..10 | ForEach-Object
{
    $_
}

# WORKS: The above needs to be written like this to work correctly:
1..10 | ForEach-Object {
    $_
}

# FAILS: This will also halt and prompt the user for a script block.
1..10 | Where-Object
{
    $_ -gt 5
}

# WORKS: The above needs to be written like this to work correctly:
1..10 | Where-Object {
    $_ -gt 5
}

# FAILS: This will throw an error that no value was provided for `-ScriptBlock` parameter.
Invoke-Command -ScriptBlock
{
    Get-Process
}

# WORKS: The above needs to be written like this to work correctly:
Invoke-Command -ScriptBlock {
    Get-Process
}

Those last 3 examples require the opening brace { to be on the same line as the cmdlet. After running into these issues for a few months, I was able to remember when an opening brace is required to be on the same line, and it has become second nature to me. It often boils down to whether it is a PowerShell keyword (e.g. if, foreach, switch), a function vs. a cmdlet, and if you are using implicit parameters or not.

That’s the problem though. It took me months to get it engrained which scenarios require the opening brace to be on the same line. Even though it’s second nature to me now, it’s not going to be for everyone, especially those new to PowerShell. Why put others through months (years?) of pain to learn when it’s ok to put the opening brace on a new line and when it’s not? Why potentially introduce bugs into your scripts, simply for the sake of a brace style?

It’s important to note that VS Code / PowerShell / PSScriptAnalyzer does not give any warnings or indications that the code will fail. It is perfectly valid syntax. This is what makes these so dangerous. The code will not fail until runtime. This means if you have the problematic code in a non-happy path, the script might run completely fine for months before finally hitting that code path and failing.

This is the primary reason I’ve switched to OTBS for PowerShell. I’m not the only person who works on my scripts, and I’m producing more open-source PowerShell these days. I want to create a pit of success for others working with my code; it should be hard to do the wrong thing. Using Allman in PowerShell means inconsistency in where the opening brace goes, creating a minefield for others to navigate. It simply isn’t worth the confusion and potential bugs it introduces.

If like me you find Allman more readable, you can experiment with inserting a blank line between blocks of code to help visually segregate them (e.g. where you used to have the opening { brace in it’s own line) and see if that helps.

Setting the default brace style in VS Code

Hopefully this post has illustrated why I’ve switched to OTBS for PowerShell, and has you considering doing the same. You can set your default PowerShell brace/indentation style in Visual Studio Code by using the powershell.codeFormatting.preset setting. Just search for PowerShell format in the VS Code Settings and you should find it. Here you can see I have it set to OTBS:

If you’re not ready to make it your default everywhere and just want to enable it for specific projects, or if you’re not the only one working on your project, switch to the Workspace tab and update the setting there. This will create a .vscode/settings.json file in your project with the setting in it:

{
  "powershell.codeFormatting.preset": "OTBS"
}

This allows you to commit the setting to source control, ensuring that everyone who works on the project uses the same brace style.

Updating your existing scripts

After updating VS Code’s PowerShell code formatting setting, you can use the Format Document command in VS Code to update the brace style of the current file.

If you want to update all of the scripts in your project at once, check out the Format Files extension.

It’s worth noting that VS Code will not automatically change the formatting of the problematic code statements mentioned in the examples above, whether you have Allman or OTBS configured, since it is valid syntax. So do not expect running Format Document to fix those issues.

The main motivation to reformat your code to use OTBS is so others looking at the code will be more likely to always put the opening brace on the same line, since that is how the rest of the script is formatted.

Conclusion

While code formatting is often just a personal choice, in PowerShell the brace style is not purely cosmetic. It can easily lead to bugs if not used correctly. To create a pit of success by not having to remember when the opening brace must be on the same line, switch to using OTBS for PowerShell.

Have you found this information helpful? Do you disagree with my reasoning? I’d love to hear your thoughts in the comments below.

Happy scripting!

The script template provides:

• A basic script structure with [CmdletBinding()] enabled.
• $InformationPreference enabled to show Write-Information messages.
• Displays the time the script started and ended, and how long it took to run.
• Uses Start-Transcript to log the script output from the last run to a file. The log file will have the same name as the script, with .LastRun.log appended to it.
  • Logging to a transcript file will incur a small performance hit, so if you need your script to be super performant, and depending on how much output your script generates, you may want to remove this.
  • If your script outputs sensitive information such as passwords or secrets, you may want to remove this, since they could end up in the unencrypted log file.

Using a template allows me to get up and running quickly, and ensures all of my scripts have a consistent structure.

Here’s the script template code:

<#
  .SYNOPSIS
  PUT SHORT SCRIPT DESCRIPTION HERE AND ADD ANY ADDITIONAL KEYWORD SECTIONS AS NEEDED (.PARAMETER, .EXAMPLE, ETC.).
#>
[CmdletBinding()]
param (
  # PUT PARAMETER DEFINITIONS HERE AND DELETE THIS COMMENT.
)

process {
  # PUT SCRIPT CODE HERE AND DELETE THIS COMMENT.
}

begin {
  # DEFINE FUNCTIONS HERE AND DELETE THIS COMMENT.

  $InformationPreference = 'Continue'
  # $VerbosePreference = 'Continue' # Uncomment this line if you want to see verbose messages.

  # Log all script output to a file for easy reference later if needed.
  [string] $lastRunLogFilePath = "$PSCommandPath.LastRun.log"
  Start-Transcript -Path $lastRunLogFilePath

  # Display the time that this script started running.
  [DateTime] $startTime = Get-Date
  Write-Information "Starting script at '$($startTime.ToString('u'))'."
}

end {
  # Display the time that this script finished running, and how long it took to run.
  [DateTime] $finishTime = Get-Date
  [TimeSpan] $elapsedTime = $finishTime - $startTime
  Write-Information "Finished script at '$($finishTime.ToString('u'))'. Took '$elapsedTime' to run."

  Stop-Transcript
}

I also have the template stored as a GitHub gist here, which may be more up-to-date than the code in this post.

I often use this template to create standalone scripts that I run directly, rather than calling them from other scripts (I would typically create a module instead for those types of reusable functions). This is the reason that I set the $InformationPreference and $VerbosePreference in the begin block and start a transcript. If you’re calling the script from another script, you likely want to remove those lines and rely on the calling script to pass in the preference parameters via the CmdletBinding and start the transcript itself.

I typically define all of my functions in the begin block, and then call them from the process block as needed. I also put the process block before the begin and end blocks. This helps keep the primary script code (in the process block) front-and-center at the top of the script, and makes it easier to see what the script is doing at a glance. If I need to see the details of a function I can use F12 to jump to the function definition. Often times I just want a high-level overview of what the script is doing though, and reading the process block provides that. I like to think of the process block like the table of contents or list of chapters in a book; it gives you a quick high-level summary of everything in the book and allows you to jump straight to the section you’re interested in, without having to read the entire book.

In a traditional script without a begin block, you would need to define all of your functions before you call them, meaning you’d have to scroll down and hunt for where the script code actually starts executing commands. Following the convention of defining functions in the begin block, you can just look at the process block to see where the script actually starts executing non-boilerplate code.

Here is a contrived example of how a script using this template might look:

<#
  .SYNOPSIS
  Writes the specified text to a file.

  .DESCRIPTION
  This script writes a given text to a specified file, creating the directory if it doesn't exist.

  .PARAMETER TextToWriteToFile
  The text to write to the file.

  .PARAMETER FilePath
  The file path to write the text to, overwriting the file if it already exists.

  .EXAMPLE
  .\Script.ps1 -TextToWriteToFile "Sample Text" -FilePath "C:\Temp\Test.txt"

  .NOTES
  Ensure that you have the necessary permissions to write to the specified file path.
#>
[CmdletBinding()]
param (
  [Parameter(Mandatory = $false, HelpMessage = 'The text to write to the file.')]
  [string] $TextToWriteToFile = 'Hello, World!',

  [Parameter(Mandatory = $false, HelpMessage = 'The file path to write the text to.')]
  [string] $FilePath = "$PSScriptRoot\Test.txt"
)

process {
  Ensure-DirectoryExists -directoryPath (Split-Path -Path $FilePath -Parent)

  Write-Information "Writing the text '$TextToWriteToFile' to the file '$FilePath'."
  Write-TextToFile -text $TextToWriteToFile -filePath $FilePath
}

begin {
  function Ensure-DirectoryExists ([string] $directoryPath) {
    if (-not (Test-Path -Path $directoryPath -PathType Container))
    {
      Write-Information "Creating directory '$directoryPath'."
      New-Item -Path $directoryPath -ItemType Directory -Force > $null
    }
  }

  function Write-TextToFile ([string] $text, [string] $filePath) {
    if (Test-Path -Path $filePath -PathType Leaf) {
      Write-Warning "File '$filePath' already exists. Overwriting it."
    }

    Set-Content -Path $filePath -Value $text -Force
  }

  $InformationPreference = 'Continue'
  # $VerbosePreference = 'Continue' # Uncomment this line if you want to see verbose messages.

  # Log all script output to a file for easy reference later if needed.
  [string] $lastRunLogFilePath = "$PSCommandPath.LastRun.log"
  Start-Transcript -Path $lastRunLogFilePath

  # Display the time that this script started running.
  [DateTime] $startTime = Get-Date
  Write-Information "Starting script at '$($startTime.ToString('u'))'."
}

end {
  # Display the time that this script finished running, and how long it took to run.
  [DateTime] $finishTime = Get-Date
  [TimeSpan] $elapsedTime = $finishTime - $startTime
  Write-Information "Finished script at '$($finishTime.ToString('u'))'. Took '$elapsedTime' to run."

  Stop-Transcript
}

Were you able to understand what the script does just by reading the param and process blocks at the top? Hopefully you didn’t need to read the entire script to understand that it simply writes the provided text to the provided file path. This is the benefit of putting the process block at the top of the script, and functions in the begin block. Also, often times the code in the begin and end blocks are complimentary to each other, so it makes sense to keep them together.

You may argue that the Synopsis in the comment-based help provided that information as well, and in this simple trivial example you are correct. The comment-based help should only describe the goal of the script and how to use it, not the individual steps of how it accomplishes that goal. In longer scripts with many steps, the process block can provide the implementation overview or summary. I’ll note though that the process block will only give you that nice high-level overview of the script steps if you write your code for it. If you just dump all of the code directly in the process block you won’t have a nice overview; if you break the steps out into well named functions though, it can be easy to read through and understand the high-level script steps. Not everyone wants to write their code this way though, and that’s fine; it’s just what I’ve found works well for me and my team, making our scripts easier to reason about and maintain.

This template is just my own personal preference, and I’m sure there are other things you may want to add to it. Feel free to use it as-is, or modify it to suit your own needs. I personally like to keep my template minimal and only include the things that I find myself adding to every script. You may want to create an “all the bells and whistles” template to start from, or different templates for different types of scripts (e.g. a different template for non-standalone scripts).

The main point is having a boilerplate template to start from can save you time and help ensure that all of your scripts have a consistent feel.

Do you use a template for your scripts? Are you going to start after reading this? Is there anything you would add or change in the template I provided? Let me know in the comments below!

Hopefully you found this useful. Happy scripting!

Context

To give some context to my ramblings, I’ve been writing software for about 25 years, using PowerShell for over a decade, and have been fortunate to attend a number of conferences over the past 20 years. The first few were smaller conferences, but the past 15 years have typically been very Very VERY large conferences, such as Microsoft Build, TechEd, and Ignite. We’re talking 10,000 attendees, where you might have lunch with a group of people the first day and then never see them again the entire conference. To accommodate that many attendees, there were hundreds (thousands?) of sessions to pick from, and any time between sessions was often spent trying to make your way to another building to get to your next session before it started.

This was my first time attending the PowerShell Summit, my first time delivering a recorded presentation outside of my work, and my first time in a long time attending a smaller conference. Also remember that this is the point of view of a single attendee; others may have had a different experience, so take this post with a grain of salt.

The Summit

The PowerShell Summit was the opposite of these big conferences in so many ways. There were only ~400 attendees, so you were seeing the same faces each day. The conference was held in the Meydenbauer Center, with all of the sessions up on the 4th floor in one of 5 rooms that were all next door to each other. This meant the time between sessions was spent talking with the other attendees or one of the few vendors, rather than trying to find the next session room. Seeing the same faces every day meant having multiple conversations with the same individuals, and made it easier to strike up conversations and move past the usual smalltalk that most people go through when awkwardly meeting someone for the first time.

I loved getting to hear how their companies are operating, what struggles they or the company were going through, and how they are solving them. I was often able to give my perspective and tell them how I or my company had solved a similar problem or gone through a similar experience, and steer them toward a strategy or tools that could help them out. I always find these types of conversations very interesting, and get a sense of reward when I’m able to point them in a direction that will help them out. Of course there was other non-tech conversations as well, like talk about video games, home towns, the eclipse that happened on Monday, and various other things.

I’m not going to lie and say I made friends with everyone there. There were still many people that I never interacted with at all. I did however feel very comfortable talking with pretty much everyone there. Everyone was very welcoming.

I typically prefer to interact with people one on one or in small groups, as that often allows for deeper conversations. I don’t do great with surface small talk, and found myself avoiding some of the larger groups in the evenings due to my own anxiety. If I attend next year though, perhaps that will change as I’ll be more familiar with more of the returning attendees. I mention this not as a bad thing, but more-so because if you’re the type of person who enjoys the fun party group in the evenings, you’ll find some of them there. There were of course many people who opted out of the evening activities, or who also stayed in smaller groups during them, so there was a good mix of personalities.

Speaking of the evening activities, they were great, and there was more of them than I was expecting. Even though the conference started on Monday, there was a mixer on Sunday to get everyone acquainted. There was a fun game night on Monday with arcade games, axe throwing, and casino games. On Thursday there was a party with mini-golf, virtual golf, pool, ping pong, and an open bar. This left us with 2 evenings to do whatever we wanted. I went out for supper with a great group of people; other people went sightseeing. The Slack channel was very active and made it easy to find others to hang out with if you wanted to.

Also, because most attendees were staying in the same hotel, most nights you could wander down to the lobby and find a group of people to hang out and chat with if you liked. I definitely enjoyed this aspect of the conference and would encourage others to stay in the official hotel as well, as it allows you to mingle some more in the evenings if you are feeling up to it.

Vendors

Conferences like Microsoft Ignite have 100s of vendors there whose sole purpose is to try and sell you on their products. They entice you with swag, like t-shirts, power banks, stress balls, cables, chargers, socks, raffles (often you must be present to win), and so much more, but often to get it you have to suffer sit through a 5 minute (or longer) sales pitch I’ll admit that I’m a sucker for swag, and would typically bring a large bag of it back to the office to give away.

Summit was nothing like that. I believe there were only 5 or 6 vendors there, and they were not pushy at all. They still had some swag to give out which was great (I love myself some tech T-shirts 🙂), but it was very relaxed and casual conversations; not sitting through a 5 minute sales pitch, which was great.

Content and presenters

I’ve been using PowerShell for over a decade and use social media to try and stay up to date with official announcements and unofficial community rumblings. Due to this, I didn’t see too many things from the presentations that I wasn’t already aware of. Almost everything shown was something that I already had experience with, or that I had seen talked about in a social media or blog post at some point. Granted, there were often 5 sessions happening simultaneously and I could only attend one, so I’m sure I missed out on many great things and am looking forward to watching the recordings in the coming weeks. Also, I talked to many people who were newer to PowerShell (1 - 5 years), or who didn’t regularly keep up with the latest tech news, and they were getting a lot of real world value to take home from almost every session. The fact that I didn’t learn as much from many of the sessions is more of a reflection of my experience level and the particular sessions that I chose to attend, not a reflection of the quality of the content or presenters. There were a couple presentations that I did learn quite a lot, such as how to write your own feedback providers, and one on using machine learning in your Prometheus metrics for early anomaly detection and alerting.

Reflecting back, I need to remember to adjust my expectations for this type of conference. At conferences like MS Build or Ignite, there are TONS of new product announcements. In almost every session you learn about something new, because they just built it and are announcing it for the first time. In reality, the entire conference is one big sales pitch to try and sell you on their latest products and features. To get you to buy in and be locked in. This is why they can pour so much money into those huge conferences; they are trying to get you to buy their products.

The PowerShell Summit is nothing like that. They aren’t there to announce a bunch of new features that the PowerShell team created (although there were a few), or to get you to buy a product. It is a conference by the community, for the community, to share knowledge and experiences with each other. And community isn’t something that only happens once a year at the Summit; it happens all year long on social media, the PowerShell forums, the PowerShell Discord server, and blogs. Summit offers the opportunity to meet and interact with this great community in person and to dive deep into topics, which is something that is hard to do asynchronously online.

Much of the session content was a good refresher for me, and I did still learn quite a few new things. Particularly, there were a number of community modules that I had never heard of, or had heard of but never really explored, and getting to see them in action was great. There’s a couple that I’ll be adding to my toolkit. Also, getting to talk with the presenters afterward was valuable as it allowed me to ask questions and dive deeper into the content they delivered.

I must say too that the quality of the presenters was top-notch. I was surprised, considering the majority of them are just other community members like myself. Usually at other conferences there would be at least a couple sessions where I would think to myself, “This person is not cut out for presenting”. I never had that thought once at the Summit. Even if I was already familiar with the content, I still enjoyed the delivery, and found most presenters did a great job answering questions on the spot. I was very impressed.

Presenting

Speaking of presenting, I also presented a 45 minute session. I was quite nervous beforehand, but had many attendees afterward tell me that they really enjoyed the presentation and thought it went great. I ran a little over my time and had to skip my last two slides, and had a hiccup in my demos where GitHub Actions had a network issue publishing the module to the PowerShell Gallery and had to be reran, but overall I am happy with how everything turned out. I had a number of people ask questions afterward, and had some great conversations later with others about the content.

Since this was both my first time attending Summit and my first time presenting, I wanted to do something special. I created stickers to promote my tiPS module, and created a few t-shirts to give away to those who asked questions in my session.

As a presenter, I’ll say that the process of getting set up and ready to present was easy and very smooth. I’m looking forward to seeing the feedback that attendees left for me, watching the recording once it is posted in a few weeks, and am hoping to present again next year.

Update May 13, 2024: You can now find the recording of my presentation on the PowerShell.org YouTube channel here, and my slide deck here.

Summary

So was the conference worth it for me? I would definitely say yes, but for different reasons than the big conferences I had become accustom to. At those conferences I would leave with 20 pages in my notebook of things to try when I get home, because they just released hundreds of new products. At Summit I still had a few pages of things to further investigate, but also had many more people added to my LinkedIn and Twitter to keep in contact with. This conference definitely helped grow my personal network more than any other conference in the past, which is especially important with the waves of layoffs that the tech community has been going through. I liked that I was able to chat with experts and get a couple questions around best practices answered that I had been wondering about. I also had very deep conversations with a handful of individuals, like Chris Masters and DevOps Jeremy. If I attend next year, I’ll probably spend a bit more time in the hallway track, interacting with other community members and having more in-depth conversations with them.

Would I recommend this conference to someone else? Most definitely. While I personally didn’t get as much value from the sessions as I hoped due to my experience level, anyone who is novice to intermediate with PowerShell would definitely get a lot of value from the sessions, and it is a great way to level up their PowerShell skills. And of course, the networking opportunities are great, and it allows you to follow up and dive deep with other community experts to gain more clarity on topics you are interested in.

One of the coolest things about Summit was getting to meet and interact with people that I had been following on Twitter for years. Getting to put a face to the name (as some people use random pics for their online presence), shake their hand, let them know how much I appreciate their contributions, and have real conversations with them was awesome. People like Josh Hendricks, Jeff Hicks, Justin Grote, James Brundage, and many others.

Finally, I must say that Andrew Pla is a machine. Andrew had me as a guest on The PowerShell Podcast a few months ago, and I was excited to meet him in person. After working the PDQ sponsor booth for much of the day during the sessions, he was then doing interviews for several hours every evening for The PowerShell Podcast. I was super grateful for some downtime in the evenings between the sessions ending and the evening activities, but Andrew never seemed to get that and always had to be on. Whatever PDQ is paying him, he deserves a raise!

What was your experience at the PowerShell Summit like? Are you planning to attend next year? Let me know in the comments below.

Bonus

For those of you who have made it this far, I have a special announcement. I was originally planning to demo this during the lightning demos, but all of the speaker’s lightning demos got bumped off the docket since we received so many attendee submissions, which is great!

The week before Summit I spent a few hours with a proof of concept and released a new module called dumPS. It’s designed to help make exploring and debugging PowerShell from the terminal a bit quicker and easier. It’s still in the early stages and I need to add some better defaults and more functionality to it, but am excited to see where it goes. Check it out and let me know what you think.

Update May 7, 2024: I also wrote this other blog post for my company if you want to read more about my experience.

The extension still needs to manually open each file in the editor and apply the formatting, so it can take a little while to run, but it sure beats doing it manually. I hope you find this extension as helpful as I have.

Happy coding!

To access the view in the Azure portal, open up the Advisor, navigate to Workbooks (or use this link), and open the Service Retirement (Preview) workbook.

At the top you will see a list of services you are using that are being retired soon, the date they are being retired, how many of your resources will be affected, and a link to documentation about the retirement and actions to take.

Below that is a list of resources that will be affected by the service retirements you have selected in the list above. This tells you the resources’ subscription, resource group, name, type, location, tags, and a link to actions to take.

You can also export the results to Excel, making the information easy to share with others.

Having a single up-to-date view of all the services being retired, which resources will be affected, and links to documentation on actions that need to be taken is extremely helpful and convenient. Anybody in the organization is able to view the workbook, and as teams migrate their resources to newer services they are removed from the list, giving a realtime view of which resources still need attention.

Recommended Action: Set up a recurring reminder to check this workbook every month or quarter, so you can stay on top of any upcoming retirements that may affect you or your organization. Share this information with other teams so they can do the same.

If you are curious or just like to stay up-to-date, you can also toggle the workbook view to show all upcoming service retirements, not just retirements for the services that you are currently using. There is also the Azure Updates page that lists upcoming and past retirements, can be searched, and has an RSS feed that you can subscribe to.

Did you find this information as helpful as I did? Have any other related tips? Let me know in the comments below.

Cheers!

Context

I needed to find all of the Azure Cloud service (classic) resources that we had in our organization, since that service is being retired on August 31, 2024. I initially overlooked the Azure portal’s All Resources blade, which would have allowed me to filter by resource type. Along the way I discovered some other ways to browse and filter my Azure resources, and thought I’d share them here.

Spoiler: I show how to find the Classic services in the Azure Portal and Azure Resource Graph Explorer sections below.

Update: For an even better way to track down services that are being retired, check out my post on the Azure Service Retirement Workbook.

Ways to explore your Azure resources

It is important to note that all of the approaches below require you to have access to the Azure subscription you want to explore. You can only browse and search across subscriptions you have permissions for. If you are wanting to search your entire organization, ensure you have access to all subscriptions.

Azure portal

The easiest and most user-friendly way to explore your Azure resources is through the Azure portal: https://portal.azure.com.

You can use the global search bar at the top center of the web page to search for resources by name, resource type (service), or resource group. If you want to just browse your resources, navigate to the Subscriptions blade and then drill down into the resource groups and their resources to inspect them.

NOTE: To ensure you are able to view and search all of the subscriptions you have access to, click the gear icon on the top-right of the webpage and ensure the Default subscription filter is set to All subscriptions, otherwise you may not see the resources you expect.

There is also an All Resources blade that will allow you to browse, search, sort, and filter all resources in the subscriptions you have access to. It shows you the resource Name, Type, Location, Resource Group, and Subscription, and also allows you to filter your resources by Tag. This is a powerful blade that can be useful for finding resources of a specific type, in a specific location, or with a specific tag.

To solve my initial problem, I could use the All Resources blade to filter by Type Cloud service (classic).

The portal does not always expose all of the properties of a resource, or let you search or filter by them. If you are looking for something more specific, you may need to use another approach.

Azure Resource Explorer

Another way to browse resources is with the Azure Resource Explorer: https://resources.azure.com.

This can show you the API endpoints for your resources, and let you explore them in a tree view. It may also expose some properties that the portal does not. I have found this view is not that helpful on its own, but can be when used in conjunction with the other approaches below.

If you do not see the resources you expect, you may need to change the directory using the dropdown box at the top. If your organization has a lot of resources, the page can be very resource intensive and bring your browser to its knees.

Azure PowerShell module

You can leverage the Az Azure PowerShell module to explore your resources from PowerShell. The Az module is actually comprised of many different modules and can be quite large. To simply install all of the modules from the PowerShell Gallery, use the command:

Install-Module -Name Az -Repository PSGallery

However, you may prefer to only install the specific modules you need. You can view all of the various Az modules on the PowerShell Gallery.

To start, you may want to install just the Az.Resources module, which will allow you to explore your resources:

Install-Module Az.Resources -Repository PSGallery

Once installed, use Connect-AzAccount to connect to your Azure account.

Now that the module is installed and connected, you can use Get-AzResource to explore the resources in the subscription you are connected to. To list the subscriptions you have access to, use Get-AzSubscription, and to change subscriptions, use Set-AzContext -Subscription <subscription name>.

The PowerShell module exposes more properties than the portal does, and you can use regular PowerShell commands to filter and search for resources you want. You can also use the Az module to create, modify, and delete resources as well. For more information, check out the Az module documentation.

Azure CLI

If you prefer to not use PowerShell, you can use the Azure CLI instead. You will need to download and install the package that is specific to your operating system.

Once you have the CLI installed, use az login to connect to your Azure account.

Now that the CLI is installed and connected, you can use az resource list to explore the resources in the subscription you are connected to. To view all of the subscriptions you have access to, use az account list, and to change subscriptions, use az account set --subscription <subscription name>.

The CLI has subcommands for many resource types, such as az vm list or az webapp list to list just VMs or web apps. Use az --help to see all of the available commands.

The CLI may expose more properties than the portal, and allows you to also create, modify, and delete resources. For more information, check out the Azure CLI documentation.

Azure Rest API

The Azure Rest API is one of the most powerful ways to explore your resources, but it is also the most difficult.

All of the methods mentioned above use the Rest API under the hood. Using the Rest API does not allow for easy browsing of your resources like the approaches above, as you often need to know the API endpoint for the resource you are looking for. This is where the Azure Resource Explorer can help, as it can show you the API endpoints for your resources. Otherwise you often have to read through the API docs.

When testing the Rest API, it can be helpful to use a tool like Postman or Thunder Client for VS Code. There are client libraries that can make is easier to use the Rest API in your own code, and they have support for languages such as .NET, Java, Node.js, and Python.

For more information, see the Rest API documentation.

Azure Resource Graph Explorer

Azure Resource Graph Explorer is a service that allows you to query your Azure resources using the Kusto query language. It is extremely powerful, and you can use it from the Portal, Azure PowerShell, Azure CLI, or the Rest API.

The easiest way to use it is from the Azure portal. From the portal, use the global search bar to search for Resource Graph Explorer, or go to https://portal.azure.com/#view/HubsExtension/ArgQueryBlade.

You will be presented with a blank query editor, a Get started view that has several example queries to choose from, and a tree view on the left with a search bar and the various resource types and their properties. The example queries can show you how to use the Kusto query language, and the tree view makes it easy to add filters to your query for the resource types and properties that you are interested in.

For example, here is a Kusto query to retrieve all of the action groups (alerts) that send email notifications to me@domain.com; something that you cannot simply search for in the Action Groups or Alerts blade of the portal:

resources
| where type == "microsoft.insights/actiongroups"
| where properties['emailReceivers'][0]['emailAddress'] == "me@domain.com"

Here is a query that could be used solve my initial problem to retrieve all of the Cloud service (classic) resources:

resources
| where type == "microsoft.classiccompute/domainnames"
| order by name desc

Here’s a screenshot of the query editor with the above query:

If needed, I could refine the query to further filter down the results based on other resource properties.

The portal allows you to download the query results as a CSV file, so they are easy to share with others. Also, unlike the PowerShell module and CLI, the Resource Graph Explorer is not scoped to a specific subscription at a time, so you can easily query across all of your subscriptions.

For more information, check out the Azure Resource Graph documentation.

When to use each tool

So we’ve seen multiple ways you can explore your Azure resources. When should you use each one?

I want to browse my resources and see what’s there.

Use the Azure portal to navigate around your subscriptions and their resources.

I want to find a specific resource, a specific type of resource, or resources with a specific property.

Start with the Portal’s global search bar. From there, try the blade for the resource type you are looking for (e.g. the Subscriptions blade). If those do not provide the searching and filtering you need, use the Azure Resource Graph Explorer.

I want to find a specific resource or property as part of an automated script.

Use the Azure PowerShell module or Azure CLI.

I want to find resources as part of my application.

Use the Azure Rest APIs with one of the client libraries. The Azure Resource Explorer may help you find the API endpoints you need, and specific properties to filter on.

Of course, these are just recommendations, and you can use whichever approach you prefer for your scenario.

Conclusion

We’ve seen several ways to get started exploring your Azure resources.

For my initial problem of finding all “Cloud service (classic)” resources, I could have also used the Azure PowerShell module or Azure CLI. The Azure Portal and Azure Resource Graph Explorer can be the easiest to get started with, as they allow you to browse through services and properties easily, which is nice when you do not know the specific properties, terms, and syntax to use. Also, they do not require any additional setup (no software to install or connecting to Azure). It all comes down using the tool you are most comfortable with though.

Hopefully you’ve learned something new and this helps you find the resources you are looking for!

Happy exploring!

While I didn’t realize it until a few days after recording, I was on the show’s 100th episode! Check out the episode on YouTube here. That is a huge accomplishment for the podcast, and I’m honoured to have been a part of it. Congratulations to Andrew and the rest of the team for reaching this milestone!

I was a little bummed that I did not get to also meet Jordan Hammond, as he decided to take a break from the show at the end of 2023. I missed out on meeting him by just a couple episodes. Even though he stopped just shy of 100 episodes, it is still a great feat and he should be proud. I hope he returns to the show in the future, even if only as a guest and to check off the “100 episodes milestone” box 😁.

Podcast additions

When writing blog posts and recording videos, I have time to gather my thoughts and later update any information that I left out. While chatting live, I don’t have that luxury. After we were done recording I was soon thinking of all the things that I could have said better, or things that I left out and should have mentioned.

If I was able to edit the podcast, these are some additional things I would have mentioned:

My PowerShell tiPS module

• The tip is delivered to your PowerShell terminal.
• Provides not only a PowerShell tip, but also:
  • Example code of what the tip describes.
  • Links to external sources for more information.
  • Categorizes the tip (e.g. Performance, Security, Syntax, Terminal, Module, Community, etc.).

Is getting a certification worth it?

• The exams can be a bit expensive, but often your employer will pay for them if you ask.
  • If you attend a conference, such as MS Build or Ignite, you can often get a free exam voucher.
• Don’t get too discouraged if you have trouble passing the exam. Some people are great at traditional school and taking exams, others are not. If you are someone that struggles with traditional exams, don’t let that discourage you. The real value is in the knowledge you gain while studying for the exam. Also, the MS exams in particular I’ve found often have at least one or two “trick” questions, where they will word the question in such a way that the answer is not obvious, even for a subject that you know very well.

Working from home

• When working in the office you can build relationships with people you otherwise wouldn’t have. I’m a software developer, but have built relationships with people in other departments, such as IT, Support, HR, and Finance. Not only has this been helpful for both expected and unexpected situations (e.g. “I wonder how we bill our customers; I’ll ask Heather in Finance”), but they are also great people and I’m glad to know them.
• Having a Zoom/Teams call open all day long for your team where you all have the cameras off and are muted is a great way to reproduce the informal conversations that happen in the office. You can unmute to ask a team member a question, and others that are on the call can chime in if they choose, or just listen in. If you start a screenshare, the others can choose to watch as well if they want, and may learn something new, or tell you a better way to perform the task. This is much more organic than scheduling a meeting, and leads to more collaboration in an low-friction way.

GitOps

• GitOps typically describes how the deployed service and infrastructure should look in a declarative manner, rather than having a procedural script that describes how to get to that state. Similar to how PowerShell DSC/Puppet/Terraform/ARM templates work vs. a regular PowerShell script. Also, while a deployment pipeline is typically used to deploy a single service, GitOps is often used to deploy an entire environment, such as a Kubernetes cluster with hundreds or thousands of services.

DevOps, SRE, and Platform Engineering

• DevOps
  • Not only about monitoring how your application performs in production, but also how it is being used. This is done by adding telemetry, and can tell you things like which features are being the most used, and which ones are not used at all and can potentially be removed to reduce application complexity.
• SRE
  • Another large focus is infrastructure costs. You want to ensure the applications have redundancy, disaster recovery, and can perform well, but without being wasteful by overprovisioning resources and paying for a bunch of compute and storage that is not utilized.
  • Often focus on infrastructure security as well. This could be things like ensuring applications are only able to accept https traffic (not http), and that only up to date TLS versions are allowed.
• Platform Engineering
  • Ideally a dev team is able to just specify the git repository that contains their application code and what type of application it is (web service, background service, cron job), and the platform will take care of building and deploying the app in a safe and secure manner, including an automated rollback process in case of failure. It may also perform additional tasks, such as static code analysis, security penetration testing, vulnerability scanning, automated load testing, and more.

My favourite thing I use PowerShell for

• Anything that requires connecting to multiple remote machines to retrieve information or run commands, such as:
  • Finding IIS website certs that are expiring soon.
  • Testing web services locally to find which servers in a pool are not responding correctly.
  • Pulling down log files from servers that are not yet using distributed logging.
  • Installing or removing software or files on multiple machines.
  • Recycling IIS app pools on multiple machines.
  • Restarting servers en masse.

Conclusion

I try to hold the content I create to a high quality standard, and am often my own worst critic. Writing these amendments shows that I still have some growth to do in learning how to relax and let go of things that are not perfect with the content I create. But, I just couldn’t help myself 😅.

Overall I think the podcast went well and I had a great time. Andrew was a great host, very easy to work with, and made me feel very comfortable, both before/after recording and while talking live. He’s a true pro! I’m looking forward to doing another show in the future.

TL;DR

While I show several approaches here, the one I recommend using is the “Include approach with reusable workflows” (Approach 5), so you can skip straight to that section if you like and take in the sample code.

This sample GitHub repository contains all of the examples shown in this post, and you can see how the workflow runs look in the GitHub Actions web UI here. Feel free to fork the repo and play around with it yourself.

Background

Over the summer I created the tiPS PowerShell module in GitHub and decided to use GitHub Actions for the CI/CD process. For the past few years I have been using Azure DevOps for my CI/CD pipelines, but I wanted to try out GitHub Actions to see how it compared, especially since my code was also hosted in GitHub. The approaches I show here are ones I tried out in the tiPS project as it evolved, until settling on an approach I was happy with.

Terminology

Azure DevOps and much of the industry use the term “pipeline” to refer to the automated steps to build and deploy software, but GitHub Actions uses the term “workflow” instead. For the purposes of this post, the terms “pipeline” and “workflow” are interchangeable.

Similarly, Azure DevOps uses the term “template”, while GitHub Actions uses the term “reusable workflow”, so I may use them interchangeably as well.

The approaches

Some CI/CD criteria we want to meet in our examples are:

• Deploy to the staging environment automatically when a main branch build completes successfully.
• Manual intervention should be required to deploy to the production environment. e.g. A manual approval.
• PR builds and non-main branch builds should:
  • Not trigger automatic deployments.
  • Manual deployments should still be possible when needed.
• All builds should upload their artifacts so they can be downloaded/inspected.

The approaches we will look at are:

1. Place all of the build and deployment steps in a single workflow file.
2. Have a deploy workflow listen for when the build workflow completes (pull approach).
3. Have the build workflow trigger the deploy workflow (push approach).
4. Have the deploy workflow include the build workflow (include approach).
5. Have the deploy workflow include the build workflow, and use a template for the deployment jobs (include approach with reusable workflows).

I typically prefer to use the include approach, but I’ll show each approach so you can decide which one you prefer for a given scenario.

If you are curious or confused about any of the workflow yaml syntax shown in the examples below, checkout the workflow syntax for GitHub Actions docs.

I created this sample GitHub repository that contains all of the examples shown in this post, so you view their code and can see how they look in the GitHub Actions web UI.

In the example yaml code below, I use the “👇” emoji to call out specific things to take note of, or that have changed from one approach to the next.

Approach 1: Build and deploy with a single workflow file

Here is an example of a single workflow file that builds and deploys some code:

name: 1-single-file--build-and-deploy

on:
  pull_request:
    branches: main # Run workflow on PRs to the main branch.

  # Run workflow on pushes to any branch.
  push:

  # Allows you to run this workflow manually from the Actions tab.
  workflow_dispatch:

env:
  artifactName: buildArtifact

jobs:
  build-and-test:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout the repo source code
        uses: actions/checkout@v3

      # Steps to version, build, and test the code go here.

      - name: Upload artifact
        uses: actions/upload-artifact@v4
        with:
          name: ${{ env.artifactName }}
          path: ./ # Put the path to the build artifact files directory here.

  deploy-to-staging:
    # 👇 Only run this deploy job after the build-and-test job completes successfully.
    needs: build-and-test
    runs-on: ubuntu-latest
    # 👇 Only run on pushes (not PRs) or manual triggers to the main branch.
    if: (github.event_name == 'push' || github.event_name == 'workflow_dispatch') && github.ref == 'refs/heads/main'
    steps:
      - name: Download artifact
        uses: actions/download-artifact@v4
        with:
          name: ${{ env.artifactName }}
          path: ./buildArtifact

      # Steps to deploy the code go here.

  deploy-to-production:
    # 👇 Only run this deploy job after the deploy-to-staging job completes successfully.
    needs: deploy-to-staging
    runs-on: ubuntu-latest
    environment: production # Used for environment-specific variables, secrets, and approvals.
    steps:
      - name: Download artifact
        uses: actions/download-artifact@v4
        with:
          name: ${{ env.artifactName }}
          path: ./buildArtifact

      # Steps to deploy the code go here.

There are a few things to note here. First, the workflow is automatically triggered when a PR to the main branch is created, or when a change is pushed to any branch. It can also be manually triggered. Second, the workflow has 3 jobs: build-and-test, deploy-to-staging, and deploy-to-production. Notice in the deploy-to-staging job we use a conditional if statement to ensure we do not deploy if the workflow was triggered by a PR, or if the push was not for the main branch.

Technically we did not need to create separate deploy jobs, and could have just put the deployment steps in the build-and-test job. In general, it is a good idea to separate the build steps from the deployment steps to maintain a separation of concerns. A technical reason for keeping them separate is GitHub Actions allows you to add approvals to a job via the environment key. Approvals are often used to block deployments until someone manually approves it. Only jobs support an environment, and you would typically have a deployment job for each environment that you need to deploy to.

Lastly, if you do decide to use a single job for both the build and deployment steps, then you technically do not need the Upload artifact and Download artifact steps. I would still recommend using the Upload artifact step though so that the build artifact is available for download in the GitHub Actions UI, in case you need to inspect its files.

Pros and cons of using a single workflow file

Pros:

• Simple to setup, as it is only a single file.
• Workflow environment variables can be easily used by all jobs. e.g. env.artifactName

Cons:

• The workflow file may quickly grow in size as more steps and jobs are added. Having a single yaml file that is several hundred or thousands of lines long can be more difficult to maintain and daunting to look at.
• Workflow code changes are required to deploy from any branch other than main.
• If you want to deploy to multiple environments, you will need to duplicate the deployment steps for each environment (Approach 5 and the Reusable Workflows section below show how to solve this). Duplicate code is harder to maintain and can easily lead to bugs if the code is not kept in sync.

• The deployment jobs/steps will be skipped for PRs and branch builds, but will still show up in the workflow web UI. This can be confusing to users, as they may not understand why those jobs/steps were skipped and that they cannot be manually triggered.

  

• The PR builds and non-main branch builds will show up in the same 1-single-file--build-and-deploy workflow runs as the main branch builds. If there are a lot of PR runs or pushes to branches, they may bury the main branch runs, forcing you to go back several pages in the web UI to find the main branch runs to answer questions like, “When was the last time we deployed to production?”.

  )

To see what the GitHub Actions UI looks like with this approach, check out the workflow runs in the sample repository.

Approach 2: Deploy workflow listens for build workflow to complete (Pull approach)

Here is an example of a workflow file that just builds the code:

name: 2-pull--build

on:
  pull_request:
    branches: main # Run workflow on PRs to the main branch.

  # Run workflow on pushes to any branch.
  push:

  # Allows you to run this workflow manually from the Actions tab.
  workflow_dispatch:

env:
  artifactName: buildArtifact

jobs:
  build-and-test:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout the repo source code
        uses: actions/checkout@v3

      # Steps to version, build, and test the code go here.

      - name: Upload artifact
        uses: actions/upload-artifact@v4
        with:
          name: ${{ env.artifactName }}
          path: ./ # Put the path to the build artifact files directory here.

And the accompanying workflow file that deploys the code using the pull approach:

name: 2-pull--deploy

on:
  # 👇 Run workflow anytime the 2-pull--build workflow completes for the main branch.
  # Unfortunately, can not have it only run on successful builds, so it will run when builds fail too.
  workflow_run:
    workflows: 2-pull--build
    types: completed
    branches: main

  # Allows you to run this workflow manually from the Actions tab.
  workflow_dispatch:
    inputs:
      # 👇 Must specify the build artifacts to deploy when running manually.
      workflowRunId:
        description: 'The build workflow run ID containing the artifacts to use. The run ID can be found in the URL of the build workflow run.'
        type: number
        required: true

env:
  artifactName: buildArtifact # This must match the artifact name in the 2-pull--build workflow.
  # 👇 Ternary operator to use input value if manually triggered, otherwise use the workflow_run.id of the workflow run that triggered this one.
  workflowRunId: ${{ github.event_name == 'workflow_dispatch' && inputs.workflowRunId || github.event.workflow_run.id }}

jobs:
  deploy-to-staging:
    # 👇 Only run the deployment if manually triggered, or the build workflow that triggered this succeeded.
    if: ${{ github.event_name == 'workflow_dispatch' || github.event.workflow_run.conclusion == 'success' }}
    runs-on: ubuntu-latest
    steps:
      # 👇 Must use a 3rd party action to download artifacts from other workflows.
      - name: Download artifact from triggered workflow
        uses: dawidd6/action-download-artifact@v2
        with:
          run_id: ${{ env.workflowRunId }}
          name: ${{ env.artifactName}}
          path: ./buildArtifact
          search_artifacts: true

      # Steps to deploy the code go here.

  deploy-to-production:
    # Only run this deploy job after the deploy-to-staging job completes successfully.
    needs: deploy-to-staging
    runs-on: ubuntu-latest
    environment: production # Used for environment-specific variables, secrets, and approvals.
    steps:
      # Must use a 3rd party action to download artifacts from other workflows.
      - name: Download artifact from triggered workflow
        uses: dawidd6/action-download-artifact@v2
        with:
          run_id: ${{ env.workflowRunId }}
          name: ${{ env.artifactName}}
          path: ./buildArtifact
          search_artifacts: true

      # Steps to deploy the code go here.

Here the build workflow is separate from the deployment workflow. The build workflow is triggered when there is a push to any branch, a PR to the main branch, or when manually triggered. The deployment workflow uses the on.workflow_run trigger to wait and listen for the build workflow to complete against the main branch.

Because the build uses its own workflow, the deployment workflow needs a reference to the build’s workflow run ID so it knows which build run to download the artifacts from. This is provided automatically when the build triggers the deployment workflow, but must be provided manually when the deployment workflow is manually triggered. You can find the build workflow run ID by opening the build workflow run in the GitHub Actions UI and looking at the URL. The URL will look something like https://github.com/deadlydog/GitHub.Experiment.CiCdApproachesWithGitHubActions/actions/runs/6985605790, where the run ID is 6985605790.

The next thing to note is that the artifactName environment variable is duplicated in both the build and deployment workflows. We could have the build workflow create an output variable that the deployment workflow could reference, but for the sake of simplicity I just duplicated the environment variable here.

Next, notice that the deploy-to-staging job has a conditional if statement that will only run the job if the workflow was manually triggered, or if the build workflow completed successfully. Unfortunately, at this time, the on.workflow_run event does not have a property to indicate that the deploy workflow should only be triggered if the build workflow completed successfully, so we have to do the check ourselves on the job.

Lastly, the deployment jobs use a 3rd party action to download the build artifact. At this time, GitHub Actions does not have a built-in action to download artifacts from other workflows. They do provide API endpoints to download artifacts from other workflows, but it is simpler to use the 3rd party action.

Pros and cons of using the pull approach

Pros:

• The build and deployment steps are separated into their own workflows, making them easier to maintain and understand.

• The build workflow only shows the build steps in the GitHub Actions UI, and the deployment workflow only shows the deployment steps, so we do not constantly have “skipped” jobs for non-deployment builds like in the previous single-workflow-file approach.

  

• Non-main branches and PRs can be manually deployed without any workflow code changes.
• Builds for PRs and non-main branches that we do not want deployed do not trigger deployment workflows.

Cons:

• The deployment workflow is triggered even if the build workflow for the main branch fails, resulting in skipped deployment runs showing in the workflow UI. This can be confusing to users, and it clutters the workflow UI.

  

• The name of the deployment workflow run is always 2-pull--deploy, rather than the commit message of the build workflow run that triggered it. It also does not show the commit SHA. This can make it difficult to find the deployment workflow run you are looking for in the GitHub UI.

  

• Certain variables must be duplicated between the build and deployment workflows (e.g. env.artifactName), or additional code added to pass the variables between the workflows.

To see what the GitHub Actions UI looks like with this approach, check out the workflows in the sample repository for the pull build runs and pull deploy runs.

Similarities to Azure DevOps classic pipelines

After using Azure DevOps classic pipelines for years, this approach felt very natural and is probably the one most similar to classic pipelines. In Azure DevOps, you would explicitly create separate build and deployment pipelines, and the first step of the deployment pipeline setup is specifying the build pipeline that it should pull the artifacts from, and potentially automatically trigger off of. So the build pipeline would not know anything about the deployment pipeline, and the deployment pipeline could be automatically triggered when the build pipeline completed successfully.

This approach worked quite well in GitHub at first, but I really did not like how blank, skipped deployment workflow runs got created when the main branch build failed. It quickly cluttered up the deployment runs when issues were encountered with the build workflow that took many attempts to fix. Also, having every deployment run named the same thing made finding a specific deployment very painful.

Listening for other events to trigger the deployment workflow

Rather than triggering the deployment workflow when a build workflow completes, you may want to trigger the deployment workflow on other events, such as when a new image is uploaded to a container registry, or when a new release is created. These are valid scenarios that may be suitable for your project. One thing to consider is that you will either need to no longer upload the artifact to the container registry for non-main branch builds, meaning you are not able to inspect and test them, or you will need to add code to your deployment workflow to determine if the artifact should be deployed or not. This may or may not be a big deal, depending on your project requirements.

Approach 3: Build workflow triggers deploy workflow (Push approach)

Here is an example of a workflow that builds the code and then triggers a deployment workflow:

name: 3-push--build

on:
  pull_request:
    branches: main # Run workflow on PRs to the main branch.

  # Run workflow on pushes to any branch.
  push:

  # Allows you to run this workflow manually from the Actions tab.
  workflow_dispatch:
    inputs:
      # 👇 Allow deploying non-main branch builds.
      deploy:
        description: 'Deploy the build artifacts. Only has effect when not building the main branch.'
        required: false
        type: boolean
        default: false

env:
  artifactName: buildArtifact

jobs:
  build-and-test:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout the repo source code
        uses: actions/checkout@v3

      # Steps to version, build, and test the code go here.

      - name: Upload artifact
        uses: actions/upload-artifact@v4
        with:
          name: ${{ env.artifactName }}
          path: ./ # Put the path to the build artifact files directory here.

  # 👇 Trigger the deployment workflow.
  trigger-deployment:
    needs: build-and-test
    # 👇 Only trigger a deployment if the deploy parameter was set, or this build is for a push (not a PR) on the default branch (main).
    if: inputs.deploy || (github.event_name != 'pull_request' && github.ref == format('refs/heads/{0}', github.event.repository.default_branch))
    uses: ./.github/workflows/3-push--deploy.yml
    # 👇 Allow the deployment workflow to access the secrets of this workflow.
    secrets: inherit

And here is the accompanying deployment workflow:

name: 3-push--deploy

on:
  # 👇 Allow this workflow to be called by the 3-push--build workflow.
  workflow_call:

env:
  artifactName: buildArtifact # This must match the artifact name in the 3-push--build workflow.

jobs:
  deploy-to-staging:
    runs-on: ubuntu-latest
    steps:
      # 👇 Can use the native download-artifact action.
      - name: Download artifact
        uses: actions/download-artifact@v4
        with:
          name: ${{ env.artifactName }}
          path: ./buildArtifact

      # Steps to deploy the code go here.

  deploy-to-production:
    # Only run this deploy job after the deploy-to-staging job completes successfully.
    needs: deploy-to-staging
    runs-on: ubuntu-latest
    environment: production # Used for environment-specific variables, secrets, and approvals.
    steps:
      - name: Download artifact
        uses: actions/download-artifact@v4
        with:
          name: ${{ env.artifactName }}
          path: ./buildArtifact

      # Steps to deploy the code go here.

Once again the build workflow is separate from the deployment workflow. The build workflow will trigger on a push to any branch, PRs to the main branch, or when manually triggered. Rather than the deploy workflow listening for the build workflow to complete, the build workflow explicitly calls the deploy workflow as its final job.

Looking at the trigger-deployment job, we can see that only builds made from the main branch will trigger the deployment workflow. A deploy parameter is also provided in the build workflow that can be set when manually triggering a build, allowing for non-main branch builds to be deployed as well, if needed. Notice that the job provides the secrets: inherit key, which allows the deployment workflow to access the secrets of the build workflow. Without this, the deployment workflow would not have access to the GitHub repository secrets.

Aside: In addition to passing secrets to the deployment workflow, you can also pass other parameters to the deployment workflow by using the with key. While none are shown in this example, I will mention that in order to pass non-string values (e.g. boolean or number), I had to use the fromJSON function to maintain the variable’s type, as shown in this GitHub issue.

Looking at the deployment workflow, you can see we are using the on: workflow_call event to allow the workflow to be called by the build workflow. Since the build workflow is triggering the deployment workflow, the end result is a single workflow run, meaning we can use the native actions/download-artifact action to download the build artifact, rather than having to use a 3rd party action.

Pros and cons of using the push approach

Pros:

• The build and deployment steps are separated into their own workflows, making them easier to maintain and understand.
• Non-main branches and PRs can be manually deployed without any workflow code changes.
• Builds for PRs and non-main branches that we do not want deployed do not trigger deployment workflows.

Cons:

• Since the deployment workflow is never triggered by GitHub, but is instead called by the build workflow, it means the deployment workflow will never show any runs.

  

  Instead, the deploy jobs will show up as part of the build workflow run. This means that builds for PRs and non-main branches will be mixed in with the main branch builds and deployments. Just like with the 1-single-file--build-and-deploy approach, this may bury the deployments under several pages of non-main branch runs, making it difficult to find runs you care about in the GitHub UI.

  

• Since the deployment jobs show up in the build workflow run, the GitHub UI prefixes each of the deployment jobs with the name of the job from the build workflow. This can make it difficult to see the full name of the deployment jobs in the generated diagram. Thankfully, the jobs are listed on the left in a tree view as well, so you can still read the full name there more easily.

  

To see what the GitHub Actions UI looks like with this approach, check out the workflows in the sample repository for the push build runs and push deploy runs.

Approach 4: Deploy workflow includes build workflow (Include approach)

Here is an example of a workflow that builds the code:

name: 4-include--build

on:
  pull_request:
    branches: main # Run workflow on PRs to the main branch.

  # 👇 Run workflow on pushes to any branch, except the main branch.
  push:
    branches-ignore: main

  # Allows you to run this workflow manually from the Actions tab.
  workflow_dispatch:

  # 👇 Allows this workflow to be called from the deployment workflow.
  workflow_call:

env:
  artifactName: buildArtifact

jobs:
  build-and-test:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout the repo source code
        uses: actions/checkout@v3

      # Steps to version, build, and test the code go here.

      - name: Upload artifact
        uses: actions/upload-artifact@v4
        with:
          name: ${{ env.artifactName }}
          path: ./ # Put the path to the build artifact files directory here.

And here is the accompanying deployment workflow:

name: 4-include--deploy

on:
  # 👇 Trigger the workflow on a push to the main branch.
  push:
    branches: main

  # 👇 Allows you to run this workflow manually (for any branch) from the Actions tab.
  workflow_dispatch:

env:
  artifactName: buildArtifact # This must match the artifact name in the 4-include--build workflow.

jobs:
  # 👇 Call the build workflow to create the artifacts to deploy.
  build-and-test:
    uses: ./.github/workflows/4-include--build.yml
    secrets: inherit # Pass secrets to the build workflow, if necessary.

  deploy-to-staging:
    # 👇 Only run this deploy job after the build-and-test job completes successfully.
    needs: build-and-test
    runs-on: ubuntu-latest
    steps:
      - name: Download artifact
        uses: actions/download-artifact@v4
        with:
          name: ${{ env.artifactName }}
          path: ./buildArtifact

      # Steps to deploy the code go here.

  deploy-to-production:
    # Only run this deploy job after the deploy-to-staging job completes successfully.
    needs: deploy-to-staging
    runs-on: ubuntu-latest
    environment: production # Used for environment-specific variables, secrets, and approvals.
    steps:
      - name: Download artifact
        uses: actions/download-artifact@v4
        with:
          name: ${{ env.artifactName }}
          path: ./buildArtifact

      # Steps to deploy the code go here.

You will notice that we still have separate build and deployment workflows. One key difference here is the specific triggers for each workflow. They have been set up so that the build workflow is only triggered by non-deployment builds, and the deployment workflow is triggered by builds that are meant to be deployed.

The build workflow will trigger on a push to any branch EXCEPT the main branch, PRs to the main branch, or when manually triggered. It also allows other workflows to call it via the workflow_call event. The build workflow no longer triggers deployments, neither directly (push) nor indirectly (pull).

The deployment workflow will now trigger on a push to the main branch, or when manually triggered. The manual trigger allows non-main branch deployments if needed. A key thing to note here is that the deployment workflow includes the build workflow via the uses key, so when a deployment is triggered it will first run the build jobs as part of its workflow run. This is similar to the push approach mentioned earlier, except that the dependency has been inverted so instead of the build workflow calling the deployment workflow, the deployment workflow calls the build workflow. This improves the workflow UI experience, as the deployment jobs will show up as part of the deployment workflow run, rather than the build workflow run like they did with the push approach.

I came across this approach on this excellent blog post when I wasn’t satisfied with the pull and push approaches.

Pros and cons of using the include approach

Pros:

• Builds for PRs and non-main branches that we do not want deployed do not trigger deployment workflows, and show up in the GitHub UI under the build workflow. These are typically throwaway builds, so it is nice to not have them cluttering up the deployment workflow runs.
• Builds that are deployed show up in the GitHub UI under the deployment workflow, making it easy to find the last time a deployment occurred.
• Non-main branches and PRs can be manually deployed without any workflow code changes.

Cons:

• In the deployment workflow run GitHub UI, the build job name is prefixed with the name of the build job in the deployment workflow, which is a minor annoyance.

  

To see what the GitHub Actions UI looks like with this approach, check out the workflows in the sample repository for the include build runs and include deploy runs.

Reusable workflows (templates)

You probably noticed that we are always deploying to 2 environments: staging and production. You may have even more environments that you need to deploy to. This results in a lot of duplicate code in the deployment workflows.

To avoid the duplicate code, we can use a reusable workflow to define the deployment jobs, and then include the reusable workflow in the deployment workflow. Azure DevOps calls these “templates”, but GitHub Actions calls them “reusable workflows”. You can think of a reusable workflow as a function that accepts parameters, so you define it once, and then can call it multiple times with different parameters.

One caveat to be aware of is that while templates may also include other templates, GitHub only allows up to 4 levels of template nesting. Also, a workflow may only call up to 20 other workflows, including nested ones. And just like regular workflows, reusable workflows must be placed directly in the .github/workflows directory.

See the GitHub docs on reusable workflows for more information and limitations.

Although I am only now introducing reusable workflows here, we’ve actually already been using them in the push and include approaches above, but were not calling them multiple times. Let’s see how to do that now.

Approach 5: Deploy workflow includes build workflow, and uses template for deployments (Include approach with reusable workflows)

Here is an example of a workflow that builds the code:

name: 5-include-with-deploy-template--build

on:
  pull_request:
    branches: main # Run workflow on PRs to the main branch.

  # Run workflow on pushes to any branch, except the main branch.
  push:
    branches-ignore: main

  # Allows you to run this workflow manually from the Actions tab.
  workflow_dispatch:

  # 👇 Allows this workflow to be called from the deployment workflow, but the parameters must be provided.
  workflow_call:
    inputs:
      artifactName:
        description: The name of the artifact to upload to.
        required: true
        type: string

env:
  # 👇 Provide a default artifact name for when this workflow is not called by the deployment workflow.
  artifactName: ${{ inputs.artifactName || 'buildArtifact' }}

jobs:
  build-and-test:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout the repo source code
        uses: actions/checkout@v3

      # Steps to version, build, and test the code go here.

      - name: Upload artifact
        uses: actions/upload-artifact@v4
        with:
          name: ${{ env.artifactName }}
          path: ./ # Put the path to the build artifact files directory here.

And here is the accompanying deployment workflow:

name: 5-include-with-deploy-template--deploy

on:
  # Trigger the workflow on a push to the main branch.
  push:
    branches: main

  # Allows you to run this workflow manually (for any branch) from the Actions tab.
  workflow_dispatch:

env:
  # 👇 Set the artifact name that will be used by the build and deployments, so it is now only defined in one place.
  artifactName: buildArtifact

jobs:
  # 👇 Call the build workflow to create the artifacts to deploy, and provide the artifact name.
  build-and-test:
    uses: ./.github/workflows/5-include-with-deploy-template--build.yml
    with:
      artifactName: ${{ github.env.artifactName }}
    secrets: inherit # Pass secrets to the build workflow, if necessary.

  deploy-to-staging:
    # Only run this deploy job after the build-and-test job completes successfully.
    needs: build-and-test
    # 👇 Call the deploy template with the proper environment name to deploy the artifacts.
    uses: ./.github/workflows/5-include-with-deploy-template--deploy-template.yml
    with:
      artifactName: ${{ github.env.artifactName }}
      environmentName: staging
    secrets: inherit # Pass repository secrets to the deployment workflow.

  deploy-to-production:
    # Only run this deploy job after the deploy-to-staging job completes successfully.
    needs: deploy-to-staging
    # 👇 Call the deploy template with the proper environment name to deploy the artifacts.
    uses: ./.github/workflows/5-include-with-deploy-template--deploy-template.yml
    with:
      artifactName: ${{ github.env.artifactName }}
      environmentName: production
    secrets: inherit # Pass repository secrets to the deployment workflow.