Basic PowerShell Script Design

The first thing you’re going to do (after getting into the ISE tool and starting a new blank script) is to set
up a parameter. Scripts in the Enterprise setting are often not hard-coded against a single object. While
being specific can be useful in automation if you have scripts that run unattended, for administration
purposes you’ll usually want to be able to specify the target(s) of your script. This particular script will
look at the last time a user set their password in Active Directory, which is a fairly common way of
looking for accounts that should be expired. For this script, you’ll want to declare a string parameter to
hold the username(s) given as input to the script for checking.

Once you’ve got the parameter declared, you’ll want to set up a simple loop. This can be a while,
do/while, or foreach construction depending on your preference. What you’re after is setting up a
structure that will display each user’s last password change date. When designing the example script, I
used a ForEach structure, but there’s no real right or wrong on this so use whatever you can get to work
the easiest. The difference between the various loop types is largely in readability and comfort level of
the programmer.

To get information about the users that you give the script, your loop will need to use the get-aduser
cmdlet to access their information. If you run “get-aduser –identity “username” –properties *” in your
PowerShell prompt (where “username” is an actual username in your AD setup without the quotes)
you’ll get a listing of all possible properties that are attached to the user. You are looking for the last
time the password was set in the system. Once you’ve figured out which property you need, you can
use this knowledge to only output the information that you’re looking for in the script.

In order to make the output of the script as legible as possible, you’re going to do some formatting of
the output. When you have your cmdlet written to get the appropriate information from a user, you can
then pipe it (using the | on your keyboard) into a ft command. ft is short for format table in PowerShell
and allows you to make a legible output from your command. The usage is simply “ft property,
property, property” for however many things you want to add to the table. In your case, you’re
interested in the name of the user and their password set date. So in pseudocode you’d do something
like “get-aduser –identity $usernamevariable –properties *|ft usernameproperty,passwordproperty”.
You’ll want to fill in actual values for the variable and properties in that example, the ones give don’t
actually work, they are solely for illustration of what you should be going for.

So, at this point you should have your script set up such that a user can run the script with one or more
usernames as input and get a legible table out with the name of each user and when they last set their
password. However, there are a couple of issues with the script in real-world usage. The first issue is
that the parameter is (probably) not a mandatory requirement (unless you set it that way already, good
for you if you did). As this is the case, your script will not actually do anything without one or more
username supplied to it, and as such this should be made mandatory. Go ahead and make this a
requirement as discussed in class yesterday.

The other issue for deployment is that you need to give users enough information to use the script
appropriately. If you run help against a cmdlet that is built into the system, you get a nice description of
what it does, what’s required to make it work, and any other details the programmers thought you
should know. You can provide this same information to help for scripts that you write; it’s a good habit
to get into.
To set up this help system, you’re going to need to add some information to the top of your script. To
do this, you’ll use a long and specially-formatted comment at the top of your script. This comment will
start with <# and end with #>. Everything between those markers will be ignored for execution (this is
also true for large in-line comments in a script you might want to write). Within the comment, you can
offer various information to the help system. This information is offered by using the format ‘.HEADING’
and then whatever you type before the next .HEADING will show up under it in the help text. For
example, if I wrote:

<#

.SYNOPSIS

Shows when a user last reset their password.

#>

With that example, a help command on the script would display the Synopsis, which is a very short
summary of the script functionality. Common headings and information provided to help are:

 Synopsis: a short description of functionality

 Description: a more detailed explanation of how the script provides it’s functionality.
 Parameter: has information about any parameters that the script will accept and what they are
used for, should also note explicitly if a parameter is required
 Example: an example of invoking the script properly with all parameters supplied. This should
be formatted such that anyone typing in the example will be able to successfully run the script.
 Link: a link to a web page containing further information about the script functionality.

You’ll need to add all of these except the Link section to your script for the assignment.

Once your script will successfully take one or more usernames as input and provide the required table
and has a fully-fleshed out help entry, you’re done with the lab. For future usage, you might think about
how the basic script you made could be extended into more complicated actions, such as disabling
accounts past a certain date (user-specified in a parameter or hard-coded) and including that
information into the output. In any case, your deliverable from the project is your script. Save a copy
and e-mail it to me (use webmail in your browser). I’ll run it on my VM and ensure that it works
correctly.