Basic PowerShell Script Design

For this lab, youll be making a basic PowerShell script and looking at one of the tools available for this
process. While in class I either showed you things directly in the PowerShell prompt or on the board,
theres actually a simple script development interface built in called PowerShell ISE. In this tool, you can
work on a script in a window and get access to things like execution previews and command-completion.
To get into this tool, just do a search for PowerShell ISE, it should pop right up. Note: if youre using
Windows 10, this tool should be available on your local machine; however, it does not include the Active
Directory cmdlets by default, so youll want to use the copy on your VM to complete the lab.

Once in the tool, youll need to get started with a new script, as it only opens to the execution window.
Go to file->new, or just the new icon on the bar (first one on the left). Youll get a split-pane design
where your script development is done at the top and at any time you can hit the Run Script button (F5
as a shortcut or the green arrow on the icon bar) to see what the current results of your script would be.
On the right side pane you have a list of all available cmdlets to look at, with the ability to get a help
pane on them by clicking on the cmdlet name. You can also click on Show Details to get a detailed listing
of all of the optional components that can be added to the cmdlet to control its behavior. You can fill
these in, click copy at the bottom, and then paste the result into your script to simplify constructing
complicated interactions if you would rather not type them out.

With the tool, youre going to do your first PowerShell script. For this script, youll be using several of
the techniques that weve gone through in class such as parameters, loops, and variables. Youll also be
looking at some additional stuff we didnt have time to cover related to providing documentation for
your script. You will see that it is possible to easily add information to your script such that if a user runs
the help command against it they will receive useful information about the functionality and scope of
the script.

The first thing youre 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 youll 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, youll want to declare a string parameter to
hold the username(s) given as input to the script for checking.

Once youve got the parameter declared, youll want to set up a simple loop. This can be a while,
do/while, or foreach construction depending on your preference. What youre after is setting up a
structure that will display each users last password change date. When designing the example script, I
used a ForEach structure, but theres 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)
youll 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 youve figured out which property you need, you can
use this knowledge to only output the information that youre looking for in the script.

In order to make the output of the script as legible as possible, youre 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,
youre interested in the name of the user and their password set date. So in pseudocode youd do
something like get-aduser identity $usernamevariable properties *|ft
usernameproperty,passwordproperty. Youll want to fill in actual values for the variable and properties
in that example, the ones give dont 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, whats 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; its a good habit
to get into.

To set up this help system, youre going to need to add some information to the top of your script. To
do this, youll 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 its 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.

Youll 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, youre 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). Ill run it on my VM and ensure that it works
correctly.