The Last Word In Nerd

I recently gave a lunch and learn for using methods and techniques beyond the basics for a group of my colleagues.  During this seminar, I covered Write-Host, and why it shouldn’t be used in a script.  Beyond Don Jones saying that if you use Write-Host, God kills a puppy, there are very good reasons for using alternate methods.  I read through Mr. Snover’s blog post on the matter to gain more clarification before covering the topic myself.

Mr. Snover covers two scenarios in which a person may wish to use Write-Host.  They are:

• For the purpose of conveying comforting information to the user.
• For the purpose of conveying results.

I’m not one for teaching by PowerPoint, so I needed to find a good way to relay this information by example.  So I decided to show the differences between Write-Verbose, Write-Output, and Write-Host.  So let’s start by taking a look at the offending Write-Host, and why it shouldn’t be used in a script.

Write-Host "This is a text message"

Write-Host in itself seems harmless enough.  But whenever it is added to a script, it will always be executed regardless if the user cares about seeing your messages or not.  There is no switch to make these messages go away, so you’re always stuck with them.  Furthermore, if you take a closer look…

Write-Host "This is a text message" | Get-Member

You’ll get this return:

Write-Host doesn’t even output a usable object.  This means that not only can you not get rid of the annoying messages, but you can’t even use it further in the pipe to add to a PSCustomObject output for reporting or any other purpose.

When we write a script, especially complex ones, we often feel we have an obligation to provide comforting information to the user (ie – “This script is going to do X”).  This is very helpful the first time you’re executing a script, but not something that they’ll care about often after that – unless something breaks of course.

Write-Verbose "This is a text message"

When you execute this as is, you get a blank return.  However, if you do this:

Write-Verbose "This is a text message" -Verbose

You get this:

So now you have a message that you can relay to the user, and give them the choice of looking at it, or not, so long as you have the cmdletbinding function enabled.  There are a lot of reasons that you should probably do this regardless.

The caveat with Write-Verbose, of course, is that it’s not really an object.  So if you wanted to send the message to a file or Out-Gridview (one of my personal favorites), you’ll need to find a different approach.  That’s where Write-Output comes into play.

Write-Output is for those times when you need to display information to the user, but you might want this information to be used further in the pipe as well.  So let’s see how this works:

Write-Output "This is text"

Well that looks easy enough.  Just like a Write-Host.  But let’s do this:

Write-Output "This is text" | Get-Member

Well now that’s different!

Where I find that Write-Output can be really useful is if I’m running a script where the potential output may be null.  In those instances, you don’t necessarily want to see nothing return.  A real world example of this is a script that I use to see what updates are pending on an SCCM client.  Using the CCM_SoftwareUpdate class in the ccm\ClientSDK namespace, I can query a machine and find out.

$ComputerName = "server01"
 FOREACH ($Computer in $ComputerName){
 get-wmiobject -ComputerName $Computer -Namespace root\ccm\ClientSDK -Class CCM_SoftwareUpdate | Select-Object * |
 ForEach-Object {
 $PSItem.EvaluationState = [regex]::Replace($PSItem.EvaluationState,"0","None");
 $PSItem.EvaluationState = [regex]::Replace($PSItem.EvaluationState,"1","Available");
 $PSItem.EvaluationState = [regex]::Replace($PSItem.EvaluationState,"2","Submitted");
 $PSItem.EvaluationState = [regex]::Replace($PSItem.EvaluationState,"3","Detecting");
 $PSItem.EvaluationState = [regex]::Replace($PSItem.EvaluationState,"4","PreDownload");
 $PSItem.EvaluationState = [regex]::Replace($PSItem.EvaluationState,"5","Downloading");
 $PSItem.EvaluationState = [regex]::Replace($PSItem.EvaluationState,"6","WaitInstall");
 $PSItem.EvaluationState = [regex]::Replace($PSItem.EvaluationState,"7","Installing");
 $PSItem.EvaluationState = [regex]::Replace($PSItem.EvaluationState,"8","PendingReboot");
 $PSItem.EvaluationState = [regex]::Replace($PSItem.EvaluationState,"9","PendingReboot");
 $PSItem.EvaluationState = [regex]::Replace($PSItem.EvaluationState,"10","PendingReboot");
 $PSItem.EvaluationState = [regex]::Replace($PSItem.EvaluationState,"11","Verifying");
 $PSItem.EvaluationState = [regex]::Replace($PSItem.EvaluationState,"12","InstallComplete");
 $PSItem.EvaluationState = [regex]::Replace($PSItem.EvaluationState,"13","Error");
 $PSItem.EvaluationState = [regex]::Replace($PSItem.EvaluationState,"14","WaitServiceWindow");
 $PSItem.EvaluationState = [regex]::Replace($PSItem.EvaluationState,"15","WaitUserLogon");
 $PSItem.EvaluationState = [regex]::Replace($PSItem.EvaluationState,"16","WaitUserLogoff");
 $PSItem.EvaluationState = [regex]::Replace($PSItem.EvaluationState,"17","WaitJobUserLogon");
 $PSItem.EvaluationState = [regex]::Replace($PSItem.EvaluationState,"18","WaitUserReconnect");
 $PSItem.EvaluationState = [regex]::Replace($PSItem.EvaluationState,"19","PendingUserLogoff");
 $PSItem.EvaluationState = [regex]::Replace($PSItem.EvaluationState,"20","PendingUpdate");
 $PSItem.EvaluationState = [regex]::Replace($PSItem.EvaluationState,"21","WaitingRetry");
 $PSItem.EvaluationState = [regex]::Replace($PSItem.EvaluationState,"22","WaitPresModeOff");
 $PSItem.EvaluationState = [regex]::Replace($PSItem.EvaluationState,"23","WaitForOrchestration");
 return $PSItem;}

}#End FOREACH

When I run  this against a machine that has updates outstanding, I get a return like so:

But when I run this against a fully compliant machine, I just get an empty return.  So instead, we modify our code with some logic to Write-Output in event of no updates found, and wrap that in a label that will be recognized :

$ComputerName = "SERVER01"
 FOREACH ($Computer in $ComputerName){
 $Update = 
 get-wmiobject -ComputerName $Computer -Namespace root\ccm\ClientSDK -Class CCM_SoftwareUpdate | Select-Object * |
 ForEach-Object {
 $PSItem.EvaluationState = [regex]::Replace($PSItem.EvaluationState,"0","None");
 $PSItem.EvaluationState = [regex]::Replace($PSItem.EvaluationState,"1","Available");
 $PSItem.EvaluationState = [regex]::Replace($PSItem.EvaluationState,"2","Submitted");
 $PSItem.EvaluationState = [regex]::Replace($PSItem.EvaluationState,"3","Detecting");
 $PSItem.EvaluationState = [regex]::Replace($PSItem.EvaluationState,"4","PreDownload");
 $PSItem.EvaluationState = [regex]::Replace($PSItem.EvaluationState,"5","Downloading");
 $PSItem.EvaluationState = [regex]::Replace($PSItem.EvaluationState,"6","WaitInstall");
 $PSItem.EvaluationState = [regex]::Replace($PSItem.EvaluationState,"7","Installing");
 $PSItem.EvaluationState = [regex]::Replace($PSItem.EvaluationState,"8","PendingReboot");
 $PSItem.EvaluationState = [regex]::Replace($PSItem.EvaluationState,"9","PendingReboot");
 $PSItem.EvaluationState = [regex]::Replace($PSItem.EvaluationState,"10","PendingReboot");
 $PSItem.EvaluationState = [regex]::Replace($PSItem.EvaluationState,"11","Verifying");
 $PSItem.EvaluationState = [regex]::Replace($PSItem.EvaluationState,"12","InstallComplete");
 $PSItem.EvaluationState = [regex]::Replace($PSItem.EvaluationState,"13","Error");
 $PSItem.EvaluationState = [regex]::Replace($PSItem.EvaluationState,"14","WaitServiceWindow");
 $PSItem.EvaluationState = [regex]::Replace($PSItem.EvaluationState,"15","WaitUserLogon");
 $PSItem.EvaluationState = [regex]::Replace($PSItem.EvaluationState,"16","WaitUserLogoff");
 $PSItem.EvaluationState = [regex]::Replace($PSItem.EvaluationState,"17","WaitJobUserLogon");
 $PSItem.EvaluationState = [regex]::Replace($PSItem.EvaluationState,"18","WaitUserReconnect");
 $PSItem.EvaluationState = [regex]::Replace($PSItem.EvaluationState,"19","PendingUserLogoff");
 $PSItem.EvaluationState = [regex]::Replace($PSItem.EvaluationState,"20","PendingUpdate");
 $PSItem.EvaluationState = [regex]::Replace($PSItem.EvaluationState,"21","WaitingRetry");
 $PSItem.EvaluationState = [regex]::Replace($PSItem.EvaluationState,"22","WaitPresModeOff");
 $PSItem.EvaluationState = [regex]::Replace($PSItem.EvaluationState,"23","WaitForOrchestration");
 return $PSItem;} | Select-Object -First 1
If ($Update.count -eq 0){$Update = Write-Output "$Computer does not have any updates available."
 [PSCustomObject]@{
 "Name" = $Update}
 }#EndPSCustomObject
Else {$Update}

}

Now when we run our script:

And that looks a lot better.  Better yet, we can array our machines, and send it to Out-Gridview and we have a nice little report with a full accounting of the list.

Write-Host allows you to do fun and cool things like change the color of the text and stuff.  But when we’re building tools, we’re looking to build something useful that requires as little intervention by the user as possible.  Leave the coloring and formatting to Word and Excel when you need it.

As a patch guy, I get asked this very question at least once a month.  The phrasing may vary, but it’s usually along the lines of:

• My application broke, did you patch it?
• My server rebooted, did you patch it?

Et cetera, et cetera.. Continue reading “PowerShell – Did You Patch My Server?”

PowerShell is a superb tool for digging directly into the systems and getting the information you need.  Sometimes though, getting exactly what you’re looking for isn’t readily available.  For example, say I want to get the ACLs for my scripting directory, I just:

Get-Acl -Path c:\scripts | Format-Table -AutoSize -Wrap

And I get this:

Cool to be sure, but if you look closely, you’ll see that the Access field is concatenated data.  The user, the access control type, and file system rights are all one string.  Not bad for reading, but if I want some kind of report to send to the boss (a la CSV), or use the output at a later time to reapply/compare permissions, it might not be acceptable.  Furthermore, we’ve formatted the data, making it essentially useless at this point if we want to move it through the pipeline.  But if you expand the Access property like so:

$Path = "c:\scripts"
$Directory = Get-Acl -Path $Path
$Directory.Access

We get the data broken down by it’s subproperties:

This is something we can work with!  But maybe I want the path too.  So let’s see if it’s available.

$Directory.Access | Get-Member

And we get:

Not exactly screaming out any winners here.  But we did have the file path in the Get-ACL.  So how do we put this all together in a single return?  How about with a PSCustomObject?

PSCustomObjects are a lot like hash tables.  They use name-value pairs like hash tables, but offer you a little more flexibility like allowing you to control the order in which they’re presented.  This makes them very nice for gathering the data you need, ordering it however you like (as far left as possible), and letting you move it through the pipe to be used or exported.  There’s some good reading to be had regarding PSCustomObjects in about_Object_Creation in PowerShell’s Get-Help or on TechNet.

So for our first example, let’s get the file path, the directory owner, and then the group, the access type, and the folder rights.  To do this, we’ll need to grab data from our Path variable, our Get-ACL cmdlet, and the Access property.  So we modify our original lines of code with a ForEach statement to call out the Access property to get our group list:

$Path = "c:\scripts"
$Directory = Get-Acl -Path $Path
ForEach ($Dir in $Directory.Access){}

And then we’ll create our PSCustomObject table inside the ForEach statement:

$Path = "c:\scripts"
$Directory = Get-Acl -Path $Path
ForEach ($Dir in $Directory.Access){
[PSCustomObject]@{
Path = $Path
Owner = $Directory.Owner
Group = $Dir.IdentityReference
AccessType = $Dir.AccessControlType
Rights = $Dir.FileSystemRights
}#EndPSCustomObject
}#EndForEach

And then we execute…

Success!  So now we can make our script a function and feed it some parameters and we can get our ACLs by group for a directory!

But we’re not done yet!

Oftentimes, I get asked from my colleagues if there’s a quick and easy way to retrieve network adapter information from machines on the network.  Those requests often include IP Address, DNS Settings, driver information and link speed.  Using Get-CIMInstance, we can retrieve the network adapter configuration for a machine by leveraging the Win32_NetworkAdapterConfiguration class.

This class gives us a wealth of information on the adapter config, but lacks the driver info and link speed that I mentioned earlier.  Using the Get-NetAdapter cmdlet, however, will net us that information that we’re missing.

For your information, you could also use the Get-CIMInstance cmdlet and target the MSFT_NetAdapter class in the root\standardcimv2 Namespace, but since we have a cmdlet that does all of the heavy lifting for us, we’ll go ahead and use that.

So, now that we know how to get the data we want, let’s go ahead and put together our list in a PSCustomObject like before:

$Computer = "server01"
$AdapterCfg = (Get-CIMInstance Win32_NetworkAdapterConfiguration -ComputerName $Computer).where({$PSItem.IPEnabled})
$NetAdapter = Get-NetAdapter -CimSession $Computer

[PSCustomObject]@{
System = $AdapterCfg.PSComputerName
Description = $AdapterCfg.Description
IPAddress = $AdapterCfg.IPAddress
SubnetMask = $AdapterCfg.IPSubnet
DefaultGateway = $AdapterCfg.DefaultIPGateway
DNSServers = $AdapterCfg.DNSServerSearchOrder
DNSDomain = $AdapterCfg.DNSDomain
DNSSuffix = $AdapterCfg.DNSDomainSuffixSearchOrder
FullDNSREG = $AdapterCfg.FullDNSRegistrationEnabled
WINSLMHOST = $AdapterCfg.WINSEnableLMHostsLookup
WINSPRI = $AdapterCfg.WINSPrimaryServer
WINSSEC = $AdapterCfg.WINSSecondaryServer
DOMAINDNSREG = $AdapterCfg.DomainDNSRegistrationEnabled
DNSEnabledWINS = $AdapterCfg.DNSEnabledForWINSResolution
TCPNETBIOSOPTION = $AdapterCfg.TcpipNetbiosOptions
IsDHCPEnabled = $AdapterCfg.DHCPEnabled
AdapterName = $NetAdapter.name
Status = $NetAdapter.status
LinkSpeed = $NetAdapter.linkspeed
Driverinformation = $NetAdapter.driverinformation
DriverFilename = $NetAdapter.DriverFileName
MACAddress = $AdapterCfg.MACAddress
}#EndPSCustomObject

Success!  Well…almost…

Once thing you might have noticed is that the data you’ve collected concatenates the data for all network adapters, so if you have multiple ethernet or wireless adapters, the data is all together and you might not want that.  Also, for my purposes, I only want the adapters that are connected to the network.  So:

$Computer = "server01"
$NetAdapter = (Get-NetAdapter -CimSession $Computer).where({$PSItem.LinkSpeed -gt 1})

This will give me only my network adapters that are showing a link speed greater than 1.

Now that I’ve got my adapters, I’ll feed them through a loop to gather the additional data from the Win32_NetworkAdapterConfiguration class.  I’ll use the MAC Address to match up the network adapters.  To do that, I need to modify the MAC Address string because Get-NetAdapter displays the MAC Address with dashes, and Win32_NetworkAdapterConfiguration stores it with colons.:

ForEach ($Net in $NetAdapter){
$NetMAC = $Net.MACAddress -replace "-",":"
$AdapterCfg = (Get-CIMInstance Win32_NetworkAdapterConfiguration -ComputerName $Net.PSComputerName).where({$PSItem.MACAddress -eq $NetMAC})
}

So for the one MAC Address, we have two instances in our WMI class.  But looking further, we see that only one is actually IPEnabled.  So let’s go with that one:

(Get-CIMInstance Win32_NetworkAdapterConfiguration -ComputerName $Net.PSComputerName).where({$PSItem.MACAddress -eq $NetMAC}) | Where-Object IPEnabled -EQ $True

Now that looks a bit better!  So now let’s create our PSCustomObject table.

[PSCustomObject]@{
System = $AdapterCfg.PSComputerName
Description = $AdapterCfg.Description
IPAddress = $AdapterCfg.IPAddress
SubnetMask = $AdapterCfg.IPSubnet
DefaultGateway = $AdapterCfg.DefaultIPGateway
DNSServers = $AdapterCfg.DNSServerSearchOrder
DNSDomain = $AdapterCfg.DNSDomain
DNSSuffix = $AdapterCfg.DNSDomainSuffixSearchOrder
FullDNSREG = $AdapterCfg.FullDNSRegistrationEnabled
WINSLMHOST = $AdapterCfg.WINSEnableLMHostsLookup
WINSPRI = $AdapterCfg.WINSPrimaryServer
WINSSEC = $AdapterCfg.WINSSecondaryServer
DOMAINDNSREG = $AdapterCfg.DomainDNSRegistrationEnabled
DNSEnabledWINS = $AdapterCfg.DNSEnabledForWINSResolution
TCPNETBIOSOPTION = $AdapterCfg.TcpipNetbiosOptions
IsDHCPEnabled = $AdapterCfg.DHCPEnabled
AdapterName = $Net.name
Status = $Netr.status
LinkSpeed = $Net.linkspeed
Driverinformation = $Net.driverinformation
DriverFilename = $Net.DriverFileName
MACAddress = $AdapterCfg.MACAddress
InterfaceName = $Net.InterfaceDescription
}#EndPSCustomObject

And our return looks good!

Now we can put the finishing touches on our script to make it a full function!

PSCustomObjects can help you create some exciting tools to gather information in your environment, or feed information from different sources into other applications (such as Active Directory or SQL).  So take a little time to get to know the PSCustomObject class and it might save you some time on the back-end!

Go here if you’d like to download a copy of my ACL function.

Go here if you’d like to download a copy of my NetAdapter

Sidenote: You might notice that I’m using Where-Object as a method in my examples (.where), but my downloads leverage Where-Object in the code.  This is something specific to PowerShell 4 and later that I learned from Jeff Hicks’ presentation on PowerShell V4 New Features on Pluralsight.  If you have access to the course, I highly recommend taking a look!  I’ll be talking about the different methods available in PowerShell v4 at a later date, and why I’ve gotten so hooked on them!

I remember, back in my admin days, we had an executable called uptime.exe.  It didn’t do much, but it gave us the amount of time that a system had been up and running for – which was something useful for checking if you suspected a server had gone offline and didn’t want to log in to verify if it crashed or not.

Some months back, I wrote a PowerShell script to give me the uptime on a remote system.  It worked well, but the formatting left something to be desired.  Using Get-CimInstance, and a little PowerShell math, I came up with this:

Get-CimInstance Win32_OperatingSystem -ComputerName Server01 | Select-Object CSName,LastBootUpTime,@{Name = 'Uptime';Expression = {$PSItem.LocalDateTime - $PSItem.LastBootUpTime }}

It does well enough, but the output format isn’t the prettiest.  In particular, I’m not really happy with the uptime output, as someone may not immediately realize that the first set of digits is days.

CSName      LastBootUpTime           Uptime
------      --------------           ------
Server01    11/19/2014 1:20:02 AM    14.08:16:27.5529900

So what to do?  I did a little reading and came across one of the Scripting Guys’ posts about the New-Timespan cmdlet and how it works.  Well, we know that the LastBootUpTime is a datetime data type; and we know that the New-Timespan cmdlet takes datetime datatypes; so we should be able to hook those two up.   So let’s do this!
#Define our current date and pull the last reboot date from a machine.
$Date = Get-Date
$Reboot = Get-CimInstance Win32_OperatingSystem -ComputerName Server01 |
Select-Object CSName,LastBootUpTime

This will give us our current date and time to feed in to the New-TimeSpan cmdlet, and the LastBootUpTime from the Win32OperatingSystem class.  I’m also grabbing the system name from the CSName property to feed into my output.  Now let’s build our command:
#Put it all together to get system uptime information
New-TimeSpan -Start $Reboot.LastBootUpTime -End $Date |
Select-Object @{Label = "System Name"; Expression = {$Reboot.CSName}},@{Label = "Last Reboot Time"; Expression = {$Reboot.LastBootUpTime}},Days,Hours,Minutes,Seconds |
Format-Table -AutoSize

I formatted the table to make it a little bit cleaner and relabeled the CSName and LastBootUpTime properties to make things a bit easier to read.  Now we get the following output:

System Name      Last Reboot Time         Days Hours Minutes Seconds
-----------      ----------------         ---- ----- ------- -------
Server01         11/19/2014 1:20:02 AM    14   9     19      29

Now just add some parameterization for the computer name, maybe give it some logic to scan multiple machines, and you’ve got yourself a very fine replacement for uptime.exe.

Feel free to download the script from the TechNet Script Center.