Product and service reviews are conducted independently by our editorial team, but we sometimes make money when you click on links. Learn more.
 

The Difference Between PowerShell Scripts and PowerShell Tools

By - Source: Toms IT Pro

A common term you may hear in the PowerShell community is "tool." At first glance, this term may be referring to just a PowerShell script. You may wonder why is a PowerShell script being referred to as a tool?

Technically, a script can also be a tool, but a tool cannot be a script. There are three rough factors that differentiate a tool from a script.

  • Tools are reusable; scripts are not
  • Tools have documentation; scripts do not
  • Tools have error handling; scripts do not

The biggest difference between a tool and a script is its reusability. When you come across a problem and write a script to solve that problem, can you reuse that script again exactly as it is, without refactoring it in any way to solve another problem? If you've got a script that creates an AD user and their home folder and every time you've got to manually change the username, home folder path or any other element like this you're modifying a script; not a tool.

MORE: Best Free PowerShell Training Resources

Here's an example of a script I'll call New-User.ps1 which I'll execute by just running the script .New-User.ps1.

$userName = 'jjones'
$params = @{
    Name = $userName
    GivenName = 'Joe'
    SurName = 'Jones'
}
New-AdUser @params
New-Item -Path "\FILESERVERUsers$userName" -ItemType Folder

I'm using a $userName variable above in two spots, which is a start, but I can't run this script again for any other user. To generalize this script and to make it into a tool I need to shift all elements that are likely to change in another context to be parameters.

param(
    [Parameter()]
    [ValidateNotNullOrEmpty()]
    [string]$Username,

    [Parameter()]
    [ValidateNotNullOrEmpty()]
    [string]$FirstName,

    [Parameter()]
    [ValidateNotNullOrEmpty()]
    [string]$LastName
)

$params = @{
    Name = $userName
    GivenName = $FirstName
    SurName = $LastName
}
New-AdUser @params

New-Item -Path "\FILESERVERUsers$userName" -ItemType Folder

Now we're shifting this script into more of a tool. We've now added parameters that we can pass in at runtime when a different user is created rather than editing the script itself. This script can then be invoked and the parameters passed in: .New-User.ps1 -UserName jjones -FirstName 'Joe' -LastName 'Jones'. This will accomplish the same task, but allows for different users to be built as well. By parameterizing the script, we can now pass in other sources of users like a CSV using Import-Csv, Get-Content from a text file or any number of ways.

I wouldn't consider this a true "tool" yet though. This isn't something I'd share with others. To round this out, I also need to add some kind of error handling, perhaps some helpful comments and comment-based help.

<#
.SYNOPSIS
    This script connects to the default domain controller on a domain-joined computer to create a new AD user while also creating the user's home folder with the same name as the username.
.EXAMPLE
   PS C:> .New-User.ps1 -UserName jjones -FirstName 'Joe' -LastName 'Jones'

This example creates an AD user called jjones with a given name of Joe and a surname of Jones. It also creates a home folder for the user at \FILESERVERUsersjjones.

#>
param(
    [Parameter()]
    [ValidateNotNullOrEmpty()]
    [string]$Username,

    [Parameter()]
    [ValidateNotNullOrEmpty()]
    [string]$FirstName,

    [Parameter()]
    [ValidateNotNullOrEmpty()]
    [string]$LastName
)
try {
    #region Create the AD User
    $params = @{
        Name = $userName
        GivenName = $FirstName
        SurName = $LastName
    }
    New-AdUser @params
    #endregion

    #region Create the home folder
    New-Item -Path "\FILESERVERUsers$userName" -ItemType Folder
    #endregion
} catch {
    Write-Error -Message $_.Exception.Message
}

We have now completed our first new user tool. It has all of the essentials of a PowerShell tool. We can use it multiple times without changing any code, it's understandable with it's comment-based help and commented regions and it's controlling any exceptions thrown.

There's no black/white answer between what makes a script and a tool but by using these examples I've provided above, you'll be able to begin calling a piece of PowerShell code like it really is.

Focus on writing tools over scripts always. The code will be easier to maintain, you won't have to reinvent the wheel every other day and you'll be able to share it with others and have them understand it.

Comments