This doesn’t replace my calendar and task list, but it let’s me see events I don’t want to miss right from PowerShell. As I worked through this idea I ended up with a PowerShell module, MyTickle.psm1, that has a number of functions to managing the tickle events, as I call them. From PowerShell I can get events, add, set and remove. I thought the module would make a good Friday Fun post because it certainly isn’t a high impact project but it offers some ideas on building a module and functions that I hope you’ll find useful.

The module for right now is a single file. Here’s the file and below I’ll talk about.

#requires -version 3.0

#  ****************************************************************
#  * DO NOT USE IN A PRODUCTION ENVIRONMENT UNTIL YOU HAVE TESTED *
#  * THOROUGHLY IN A LAB ENVIRONMENT. USE AT YOUR OWN RISK.  IF   *
#  * YOU DO NOT UNDERSTAND WHAT THIS SCRIPT DOES OR HOW IT WORKS, *
#  * DO NOT USE IT OUTSIDE OF A SECURE, TEST SETTING.             *
#  ****************************************************************

#MYTICKLE.PSM1
#Last updated 5/17/2013

#region Define module variables
#This should be the WindowsPowerShell folder under your Documents folder
$profileDir = Split-Path $profile

#the path to the tickle csv file
$TicklePath = Join-Path -Path $profileDir -ChildPath "mytickler.csv"

#the default number of days to display
$TickleDefaultDays = 7 
#endregion

#region Define module functions
Function Get-TickleEvent {

.Synopsis
Get Tickle Events
.Description
Get tickle events by id or name. The default behavior is to get all events in
date order. You can specify a range of ID numbers and use wildcards with the 
event names. Use the Expired switch to get all tickle events that have already 
occurred. 

The command will not throw an exception if no matching tickle events are found.

[cmdletbinding(DefaultParameterSetname="ALL")]
Param(
[Parameter(Position=0,ParameterSetName="ID")]
[int[]]$Id,
[Parameter(Position=0,ParameterSetName="Name")]
[string]$Name,
[Parameter(Position=0,ParameterSetName="Expired")]
[switch]$Expired,
[ValidateScript({Test-Path $_} )]
[string]$Path=$TicklePath
)

Write-Verbose "Importing events from $Path"

Switch ($pscmdlet.ParameterSetName) {
 "ID"      {
            Write-Verbose "by ID" 
            $filter = [scriptblock]::Create("`$_.id -in `$id")  }
 "Name"    { 
            Write-Verbose "by Name"
            $filter = [scriptblock]::Create("`$_.Event -like `$Name") }
 "Expired" { 
            Write-Verbose "by Expiration"
            $filter = [scriptblock]::Create("`$_.Date -lt (Get-Date)") }
 "All"     { 
            Write-Verbose "All"
            $filter = [scriptblock]::Create("`$_ -match '\w+'") }

} 

#import CSV and cast properties to correct type
Import-CSV -Path $Path | 
Select @{Name="ID";Expression={[int]$_.ID}},
@{Name="Date";Expression={[datetime]$_.Date}},
Event,Comment | where $Filter | Sort date

} #Get-TickleEvent

Function Set-TickleEvent {

.Synopsis
Set a tickle event
.Description
This command will update the settings for a tickle event. You can update the
event name, date or comment. The easiest way to use this is to pipe an tickle
event to this command.

[cmdletbinding(SupportsShouldProcess,DefaultParameterSetName="Inputobject")]
Param(
[Parameter(Position=0,Mandatory,HelpMessage="Enter the tickle event id",ParameterSetName="ID")]
[int]$Id,
[Parameter(Position=1,ValueFromPipeline,ParameterSetname="Inputobject")]
[object]$Inputobject,
[datetime]$Date,
[string]$Event,
[string]$Comment,
[ValidateScript({Test-Path $_} )]
[string]$Path=$TicklePath,
[switch]$Passthru
)
Begin {
    write-verbose "Using $($PSCmdlet.ParameterSetName) parameter set"
}
Process {

#if ID only then get event from CSV
Switch ($pscmdlet.ParameterSetName) {
 "ID" {
    Write-Verbose "Getting tickle event id $ID"
    $myevent = Get-TickleEvent -id $id
   }
 "Inputobject" {
    Write-Verbose "Modifying inputobject"
    $myevent = $Inputobject
 }
} #switch

#verify we have an event to work with
if ($myevent) {
    #modify the tickle event object
    write-verbose ($myevent | out-string)

    if ($Date) {
      Write-Verbose "Setting date to $date"
      $myevent.date = $Date
    }
    if ($Event) {
      Write-Verbose "Setting event to $event"
      $myevent.event = $Event
    }
    if ($comment) {
      Write-verbose "Setting comment to $comment"
      $myevent.comment = $comment
    }
    write-verbose "Revised: $($myevent | out-string)"

    #find all lines in the CSV except the matching event
    $otherevents = get-content -path $Path | where {$_ -notmatch "^""$($myevent.id)"} 
    #remove it
    $otherevents | Out-File -FilePath $Path -Encoding ascii 

    #append the revised event to the csv file
    $myevent | Export-Csv -Path $Path -Encoding ASCII -Append -NoTypeInformation

    if ($passthru) {
        $myevent
    }
}
else {
    Write-Warning "Failed to find a valid tickle event"
}

} #process

} #Set-TickleEvent

Function Add-TickleEvent {

.Synopsis
Add a tickle event
.Description
This command will create a new tickle event. If the CSV file referenced by the
TicklePath variable does not exist, it will be created. You must enter an event 
name and date.

[cmdletbinding(SupportsShouldProcess)]

Param (
[Parameter(Position=0,ValueFromPipelineByPropertyName,Mandatory,HelpMessage="Enter the name of the event")]
[string]$Event,
[Parameter(Position=1,ValueFromPipelineByPropertyName,Mandatory,HelpMessage="Enter the datetime for the event")]
[datetime]$Date,
[Parameter(Position=2,ValueFromPipelineByPropertyName)]
[string]$Comment,
[ValidateNotNullorEmpty()]
[string]$Path=$TicklePath,
[switch]$Passthru
)

Begin {
    #verify the path and create the file if not found
    if (! (Test-Path $Path)) {
        Write-Verbose "Creating a new file: $Path"
        Try {
         '"id","Date","Event","Comment"' | 
         Out-File -FilePath $Path -Encoding ascii -ErrorAction Stop
        }
        Catch {
            Write-Warning "Failed to create $Path"
            Write-Warning $_.Exception.Message
            $NoFile = $True
        }
    }
}

Process {
if ($NoFile) {
    Write-Verbose "No CSV file found."
    #bail out of the command
    Return
}

#get last id and add 1 to it
[int]$last = Import-Csv -Path $Path | 
Sort {$_.id -AS [int]} | Select -last 1 -expand id
[int]$id = $last+1

$hash=[ordered]@{
  ID = $id
  Date = $date
  Event = $event
  Comment = $comment
}
Write-Verbose "Adding new event"
Write-Verbose ($hash | out-string)

$myevent = [pscustomobject]$hash
$myevent | Export-Csv -Path $Path -Append -Encoding ASCII -NoTypeInformation
if ($passthru) {
    $myevent
}
} #process

} #Add-TickleEvent

Function Remove-TickleEvent {

.Synopsis
Remove a tickle event
.Description
Remove one or more events from the tickle file. This will overwrite the current
file so you might want to back it up first with Backup-TickleFile.
.Example
PS C:\> get-ticklevent -expired | remove-tickleevent

[cmdletbinding(SupportsShouldProcess,DefaultParameterSetName="Inputobject")]
Param(
[Parameter(Position=0,Mandatory,HelpMessage="Enter the tickle event id",ParameterSetName="ID")]
[int]$Id,
[Parameter(Position=1,ValueFromPipeline,ParameterSetname="Inputobject")]
[object]$Inputobject,
[ValidateScript({Test-Path $_} )]
[string]$Path=$TicklePath
)

Process {

    #if ID only then get event from CSV
    Switch ($pscmdlet.ParameterSetName) {
     "ID" {
        Write-Verbose "Getting tickle event id $ID"
        $myevent = Get-TickleEvent -id $id
       }
     "Inputobject" {
        Write-Verbose "Identifying inputobject"
        $myevent = $Inputobject
     }
    } #switch

    #verify we have an event to work with
    if ($myevent) {
        Write-Verbose "Removing event"
        Write-Verbose ($myEvent | Out-String)
        if ($pscmdlet.ShouldProcess(($myEvent | Out-String))) {
        #find all lines in the CSV except the matching event
        $otherevents = Get-Content -path $Path | where {$_ -notmatch "^""$($myevent.id)"} 
        #remove it
        $otherevents | Out-File -FilePath $Path -Encoding ascii 
        }
    } #if myevent

} #process

} #Remove-TickleEvent

Function Show-TickleEvent {

.Synopsis
Display Tickle events in the console
.Description
This command gets upcoming tickle events and writes them to the console using
Write-Host. Use this command in your PowerShell profile script.

[cmdletbinding()]
Param(
[Parameter(Position=0)]
[ValidateScript({Test-Path $_})]
[string]$Path=$TicklePath,
[Parameter(Position=1)]
[ValidateScript({$_ -ge 1})]
[int]$Days = $TickleDefaultDays
)

#import events from CSV file
$events = Import-Csv -Path $Path

#get upcoming events within 7 days sorted by date
$upcoming = $events | 
where {
 #get the timespan between today and the event date
 $ts = (New-TimeSpan -Start (Get-Date) -end $_.Date).TotalHours 
 #find events less than the default days value and greater than 0
 Write-Verbose $ts
 $ts -le ($Days*24) -AND $ts -gt 0
 } |
Add-Member -MemberType ScriptProperty -Name Countdown -value {New-TimeSpan -start (Get-Date) -end $this.date} -PassThru -force|
sort CountDown

if ($upcoming) {
#how wide should the box be?
#get the length of the longest line
$l = 0
foreach ($item in $upcoming) {
 #turn countdown into a string without the milliseconds
  $count = $item.countdown.ToString()
  $time = $count.Substring(0,$count.lastindexof("."))
  #add the time as a new property
  $item | Add-Member -MemberType Noteproperty -name Time -Value $time
  $a = "$($item.event) $($item.Date) [$time]".length
  if ($a -gt $l) {$l = $a}
  $b = $item.comment.Length
  if ($b -gt $l) {$l = $b}
}

[int]$width = $l+5

$header="* Reminders $((Get-Date).ToShortDateString())"

#display events
Write-Host "`r"
Write-host "$($header.padright($width,"*"))" -ForegroundColor Cyan
Write-Host "*$(' '*($width-2))*" -ForegroundColor Cyan

foreach ($event in $upcoming) {

  if ($event.countdown.totalhours -le 24) {
    $color = "Red"
  }
  elseif ($event.countdown.totalhours -le 48) {
    $color = "Yellow"
  }
  else {
    $color = "Green"
  }

  #define the message string
  $line1 = "* $($event.event) $($event.Date) [$($event.time)]"
  if ($event.comment -match "\w+") {
   $line2 = "* $($event.Comment)"
   $line3 = "*"
  }
  else {
   $line2 = "*"
   $line3 = $null
  }

$msg = @"
$($line1.padRight($width-1))*
$($line2.padright($width-1))*
"@

if ($line3) {
    #if there was a comment add a third line that is blank
    $msg+="`n$($line3.padright($width-1))*"
}

  Write-Host $msg -ForegroundColor $color

} #foreach

Write-host ("*"*$width) -ForegroundColor Cyan
Write-Host "`r"
} #if upcoming events found
else {
  $msg = @"

**********************
* No event reminders *
**********************

"@
  Write-host $msg -foregroundcolor Green
}

} #Show-TickleEvent

Function Backup-TickleFile {

.Synopsis
Create a backup of the tickle file
.Description
This command will create a backup copy of the tickle CSV file. The default path
is the same directory as the tickle file. You might want to backup the tickle
file before removing any events.

[cmdletbinding(SupportsShouldProcess)]
Param(
[ValidateScript({Test-Path $_} )]
[string]$Path=$TicklePath,
[ValidateScript({Test-Path $_} )]
[string]$Destination = (Split-Path $TicklePath),
[switch]$Passthru
)

Try {
    $ticklefile = Get-Item -Path $path
    $backup = Join-Path -path $Destination -ChildPath "$($ticklefile.basename).bak"
    Write-Verbose "Copying $path to $backup"
    $ticklefile | Copy-Item  -Destination $backup -ErrorAction Stop -PassThru:$Passthru
}
Catch {
    Write-Warning "Failed to backup file"
    Write-Warning $_.exception.message
}
} #Backup-TickleFile
#endregion

#region Define module aliases
Set-Alias -Name gte -value Get-TickleEvent
Set-Alias -name ate -Value Add-TickleEvent
Set-Alias -name rte -Value Remove-TickleEvent
Set-Alias -name ste -Value Set-TickleEvent
Set-Alias -name shte -Value Show-TickleEvent
Set-Alias -name btf -Value Backup-Ticklefile
#endregion

Export-ModuleMember -Function * -Variable TicklePath,TickleDefaultDays -Alias *

You should be able to copy the code from the WordPress plugin and paste it into a script file locally. You can call it whatever you want just remember to use a .psm1 file extension. The module uses some PowerShell 3.0 features like ordered hashtables but you could revise to have it run in PowerShell 2.0. Fundamentally it should work in both versions.

The events are stored in a CSV file that I reference with a module variable, $TicklePath. The default is a file called mytickler.csv which will be in your WindowsPowerShell folder under Documents. The module also defines a variable called $TickleDefaultDays, with a default value of 7. This displayed events to those that fall within that range. To use, I added these lines to my PowerShell profile.

import-module c:\scripts\mytickle.psm1
show-tickleevent

The result, is that when I launch a new PowerShell session I see something like this (the message about help updates is from something else so disregard):

Here’s how it works.

The Show-TickleEvent function imports events from the CSV file that will happen within the next 7 days. Each object also gets an additional property that is a timespan object for how much time remains. The function then parses event information and constructs a “box” around the events.

#how wide should the box be?
#get the length of the longest line
$l = 0
foreach ($item in $upcoming) {
 #turn countdown into a string without the milliseconds
  $count = $item.countdown.ToString()
  $time = $count.Substring(0,$count.lastindexof("."))
  #add the time as a new property
  $item | Add-Member -MemberType Noteproperty -name Time -Value $time
  $a = "$($item.event) $($item.Date) [$time]".length
  if ($a -gt $l) {$l = $a}
  $b = $item.comment.Length
  if ($b -gt $l) {$l = $b}
}

[int]$width = $l+5

$header="* Reminders $((Get-Date).ToShortDateString())"

#display events
Write-Host "`r"
Write-Host "$($header.padright($width,"*"))" -ForegroundColor Cyan
Write-Host "*$(' '*($width-2))*" -ForegroundColor Cyan

#get upcoming events within 7 days sorted by date
$upcoming = $events |
where {
#get the timespan between today and the event date
$ts = (New-TimeSpan -Start (Get-Date) -end $_.Date).TotalHours
#find events less than the default days value and greater than 0
Write-Verbose $ts
$ts -le ($Days*24) -AND $ts -gt 0
} |
Add-Member -MemberType ScriptProperty -Name Countdown -value {New-TimeSpan -start (Get-Date) -end $this.date} -PassThru -force |
sort CountDown

I set a foreground color depending on how imminent the event is and then write each event to the console, wrapped in my border.

#define the message string
  $line1 = "* $($event.event) $($event.Date) [$($event.time)]"
  if ($event.comment -match "\w+") {
   $line2 = "* $($event.Comment)"
   $line3 = "*"
  }
  else {
   $line2 = "*"
   $line3 = $null
  }

$msg = @"
$($line1.padRight($width-1))*
$($line2.padright($width-1))*
"@

if ($line3) {
    #if there was a comment add a third line that is blank
    $msg+="`n$($line3.padright($width-1))*"
}

  Write-Host $msg -ForegroundColor $color

I purposely used Write-Host so that I could color code events and because I didn’t want the profile to write anything to the pipeline. Because the module is loaded at the start of my PowerShell session, I can always run Show-TickleEvent and event specify a different number of days. If I want objects, then I can use the Get-TickleEvent function which will import the csv events based on a criteria like ID or name. The function uses parameter sets and I create a filter scriptblock depending on the parameter set.

Switch ($pscmdlet.ParameterSetName) {
 "ID"      {
            Write-Verbose "by ID" 
            $filter = [scriptblock]::Create("`$_.id -in `$id")  }
 "Name"    { 
            Write-Verbose "by Name"
            $filter = [scriptblock]::Create("`$_.Event -like `$Name") }
 "Expired" { 
            Write-Verbose "by Expiration"
            $filter = [scriptblock]::Create("`$_.Date -lt (Get-Date)") }
 "All"     { 
            Write-Verbose "All"
            $filter = [scriptblock]::Create("`$_ -match '\w+'") }

}

When I import the CSV file, I add types to the properties because otherwise everything would be a string, and then pipe each object to my filter.

#import CSV and cast properties to correct type
Import-CSV -Path $Path | 
Select @{Name="ID";Expression={[int]$_.ID}},
@{Name="Date";Expression={[datetime]$_.Date}},
Event,Comment | where $Filter | Sort Date

These objects come in handy because they can be piped to Set-TickleEvent to modify values like event name, date or comment. Or I can pipe to Remove-TickleEvent to delete entries. The deletion process in essence finds all lines in the CSV file that don’t start with the correct id and creates a new file using the same name.

if ($pscmdlet.ShouldProcess(($myEvent | Out-String))) {
  #find all lines in the CSV except the matching event
  $otherevents = Get-Content -path $Path | where {$_ -notmatch "^""$($myevent.id)"} 
  #remove it
  $otherevents | Out-File -FilePath $Path -Encoding ascii 
 }

Finally, after accidentally wiping out event files, I added a simple backup function copies the CSV file to the same directory but with a .BAK file extension. You could specify an alternate path, but it defaults to the WindowsPowerShell folder.

Hopefully I won’t miss important events again, of course assuming I add them to my tickler file. I’ll let you play with Add-TickleEvent to see how that works or you could always modify the CSV file with Notepad.

If you actually use this, I hope you’ll let me know.

[Note: due to a limitation in the syntax plugin I use, I removed the comment characters around the help in each function. You will need to add them back.]

PS C:\> (get-wmiobject win32_operatingsystem -comp chi-dc01).OsArchitecture -match "64"
True
PS C:\> (get-wmiobject win32_operatingsystem -comp novo8).OsArchitecture -match "64"
False

If you are running PowerShell 3 you could substitute Get-CimInstance. One thing to be aware of with this particular class is that the OSArchitecture property isn’t valid on older operating systems like Windows Server 2003. You’ll get an exception.

In this case I modified the WMI query to only return the OSArchitecture property, which doesn’t exist. Otherwise I would just get false which might not be entirely true. Of course, I always get carried away so before I knew it I had turned this one line command into a function.

#requires -version 2.0

Function Test-Is64Bit {
[cmdletbinding()]

Param(
[ValidateNotNullorEmpty()]
[string]$Computername=$env:computername,
[Alias("RunAs")]
[System.Management.Automation.Credential()]$Credential = [System.Management.Automation.PSCredential]::Empty
)

Try {
  #hash table of parameters to splat
  $wmiParams = @{
    Class = 'win32_operatingsystem'
    Property = 'osarchitecture'
    ComputerName = $computername
    ErrorAction = 'Stop'
  }
  if ($credential) {
    Write-Verbose "Adding credential"
    $wmiParams.Add("Credential",$Credential)
  }
  Write-Verbose "Testing $computername"
  $data = Get-WmiObject @wmiParams
  Write-Verbose $data.OSArchitecture
  $data.OsArchitecture -match "64"

} #try

Catch {
  Switch -wildcard ($error[0].Exception.Message) {
   "The RPC Server*" { 
      Write-Warning "Can't connect to server. Verify name and availability." 
      }
   "Access is denied*" {
      Write-Warning "Access denied. Check your permissions."
      }
   "Invalid query*" {
      Write-Warning "WMI information not available. OS version may Windows 2003 or earlier."
      }
  Default { 
    Write-Error $error[0]
    }
  } #switch
} #catch

Finally {
    Write-Verbose "Finished testing"
} #finally

} #close function

The function takes a computername and optionally a PSCredential. You can use a saved PSCredential object or specify the name and you will be prompted.

The other design element is that if there is an exception caught I have a Switch statement to checks the message and writes a custom warning.

There’s no reason you can’t use the one-liner. But if you want to add a bit more robustness and create a re-usable tool, it doesn’t take much to turn it into a simple function.

Basically, my profile script checks the version first, before doing anything. You can use the $psversiontable variable.

PS C:\> $PSVersionTable

Name                           Value
----                           -----
PSVersion                      3.0
WSManStackVersion              3.0
SerializationVersion           1.1.0.1
CLRVersion                     4.0.30319.18033
BuildVersion                   6.2.9200.16434
PSCompatibleVersions           {1.0, 2.0, 3.0}
PSRemotingProtocolVersion      2.2

The PSVersion property is what I’m looking for. With this information, I can wrap my PowerShell profile script in simple IF statement.

#requires -version 2.0

<#
Use code like this in your PowerShell profile if it will
be shared between PowerShell 2 and PowerShell 3 sessions
on the same computer
#>

if ($psversiontable.psversion -eq '3.0') {
 Write-Host "You are running PowerShell 3.0" -ForegroundColor Green
 #insert 3.0 specific commands
 $PSDefaultParameterValues.Add("Format-Table:Autosize",$True)
}
else {
  Write-Host "You are running PowerShell 2.0" -ForegroundColor Yellow
  #insert 2.0 specific commands
}

#insert commands that apply to both versions

I think the comments in the code sample are pretty clear and there’s really not much else to add. The Write-Host lines are merely for testing. You don’t really need them.

Now I can get properly configured PowerShell sessions regardless of version and without errors.

get-content c:\work\computers.txt

The potential problem is that the text file may not be perfectly formatted. Your text file might have blank lines. Or your computername may have a trailing white space. These things can complicate using the text file in a PowerShell pipelined expression. One approach is to filter the content using Where-Object and simply look for the existing of something.

get-content c:\work\computers.txt | where {$_} | <something else>

This works fine in filtering out blank lines. But won’t fail if you have a line where someone inserted a tab or hit the space bar a few times. So let’s take this a bit further and use a regular expression to filter out anything that doesn’t have a non-whitespace character.

get-content c:\work\computers.txt | where {$_ -match "\w+"} | <something else>

This should get rid of any lines that are nothing but tabs or spaces. Of course, there is still the issue of leading or trailing spaces. But we can handle that by using the string object’s Trim() method.

This is starting to get complicated. So I wrote a filtering function to scrub up content presumably from text files.

#requires -version 2.0

Filter Scrub {
<#
.Synopsis
Clean input strings
.Description
This command is designed to take string input and scrub the data, filtering
out blank lines and removing leading and trailing spaces. The default behavior
is to write the object to the pipeline, however you can use -PropertyName to
add a property name value. If you use this parameter, the assumption is that
contents of the text file are a single item like a computer name.
.Example
PS C:\> get-content c:\work\computers.txt | scrub | foreach { get-wmiobject win32_operatingsystem -comp $_}
.Example
PS C:\> get-content c:\work\computers.txt | scrub -PropertyName computername | test-connection 
#>

[cmdletbinding()]
Param(
[Parameter(Position=0,ValueFromPipeline=$True)]
[string[]]$InputObject,
[string]$PropertyName
)

  #filter out blank lines
  $InputObject | where {$_ -match "\w+"} | 
  ForEach-Object { 
    #trim off trailing and leading spaces
    $clean = $_.Trim()
    if ($PropertyName) {
        #create a customobject property
        New-Object -TypeName PSObject -Property @{$PropertyName=$clean}
    }
    else {
        #write the clean object to the pipeline
        $clean
    }
    } #foreach 

} #close Scrub

We don’t use the Filter keyword much anymore but it seemed appropriate because that is the only thing Scrub is doing. In fact, I intentionally did not use a traditional verb-noun name. Technically this an advanced function this is just a Process script block. I wrote it with the assumption that you would pipe strings from Get-Content.

Each processed string is filtered to get rid of blanks and spaces. Then each string is trimmed of leading and trailing spaces and finally written to the pipeline. Now I can run a command line this:

get-content c:\scripts\computers.txt | scrub

In my initial versions this solved all of my potential problems with text files. But then I realize I had an opportunity to add one more scrubbing feature. Many cmdlets have parameters that take pipeline input by property name. But strings from text files lack a property name. So I added a parameter to my Scrub filter to add a property name.

get-content c:\scripts\computers.txt | scrub -PropertyName Computername

Now I’m writing an object to the pipeline and can take advantage of pipeline binding.

get-content c:\scripts\computers.txt | scrub -PropertyName Computername | test-connection -Count 1

I don’t know about you, but this will come in very handy. I hope you’ll let me know what you think.

If you are going to use Write-Host (and want to save puppies) to display informational or progress messages, please use one of the color parameters so that your message can be differentiated from your object output. Ideally for advanced events you should be using Write-Progress. Not sure we’ve had events that call for Write-Progress but keep it in mind.

I generally dislike entries that are clearly overwrought and over-thought. Sometimes the problem can be solved simply. Don’t feel you have to use every trick in the PowerShell play book in order to score points. I’m a big proponent of the right tool for the job. On a related note, if you can solve the challenge with a PowerShell one-liner, don’t feel you need to write it as a long single line command. Take advantage of PowerShell parsing. This is very hard to read:

Get-WmiObject win32_operatingsystem -comp $computers | select PSComputername,@{Name="TotalMemoryMB";Expression={[int]($_.TotalVisibleMemorySize/1KB)}},@{Name="FreeMemoryMB";Expression={[math]::Round($_.FreePhysicalmemory/1KB,2)}},@{Name="PercentMemoryFree";Expression={[math]::Round(($_.freephysicalmemory/$_.totalvisibleMemorySize)*100,2)}} | Sort PSComputername | Export-CSV -Path c:\work\osreport.csv -Encoding ASCII -NoTypeInformation

I’d much rather see a one-liner formatted like this:

Get-WmiObject win32_operatingsystem -comp $computers | 
select PSComputername,
@{Name="TotalMemoryMB";Expression={[int]($_.TotalVisibleMemorySize/1KB)}},
@{Name="FreeMemoryMB";Expression={[math]::Round($_.FreePhysicalmemory/1KB,2)}},
@{Name="PercentMemoryFree";
Expression={[math]::Round(($_.freephysicalmemory/$_.totalvisibleMemorySize)*100,2)}} |
Sort PSComputername | 
Export-CSV -Path c:\work\osreport.csv -Encoding ASCII -NoTypeInformation

In full scripts, I’d like to see more use of #Requires -version X so that I can tell what features you might be using. Related to that, in advanced scripts if you are using a parameter attribute like Mandatory or ValueFromPipeline, v3 scripts should use them like this:

[Parameter(Position=0,ValueFromPipeline,Mandatory)]

You don’t have to explicitly state that Mandatory is equal to True. Although in v2 you would need to do this:

[Parameter(Position=0,ValueFromPipeline=$True,Mandatory=$True)]

Which brings me to another minor irk, an object that has a boolean value doesn’t need a comparison operator. The whole point of something like an IF statement is to evaluate if the expression in the parentheses is true or not. If the object is already a boolean, there’s no need.

$found = $True

#bad form
if ($found -eq $True) {
 #deleting computer from active directory
 #...
}

#better form
if ($found) {
 #deleting computer from active directory
 #...
}

I’m also not a big fan of creating custom objects with lots of Add-Member commands. I think this makes the code harder to read and doesn’t really buy you much. I think using a hashtable with New-Object is much easier to read and just as effective. Plus in v3 we can now have ordered hashtables and even use [pscustomobject].

$os = Get-CimInstance -class win32_operatingsystem -ComputerName $computer
$computersystem = Get-CimInstance -ClassName win32_computersystem -ComputerName $computer
$is64Bit = If ($os.OSArchitecture -match "64") { $True } Else {$False}

$Inventory = [ordered]@{
Computername = $os.PSComputername
OperatingSystem = $os.Caption
Installed = $os.InstallDate
Model = $computersystem.Model
Mfg = $computersystem.Manufacturer
Is64Bit = $Is64Bit
}

[pscustomobject]$Inventory

Finally, be very careful of including formatting commands in your entries, unless the event specifically calls for it. This is especially true if you are writing a function. When you include formatting directives at the end of the function, it can’t be used anywhere else in a PowerShell expression.

Don’t get me wrong, there is a lot of good PowerShell which I’m happy to see:

• Using Join-Path to build paths
• Using Test-Path to validate
• Plenty of internal comments
• Using Test-Connection to verify computers are online
• Meaningful variable names

So keep up the good work and on to the next event!

#requires -version 3.0

Function Get-FolderSize {

<#
.Synopsis
Get a top level folder size report
.Description
This command will analyze the top level folders in a given root. It will write
a custom object to the pipeline that shows the number of files in each folder,
the total size in bytes and folder attributes. The output will also include 
files in the root of the specified path.

Sample output:
Name       : DesktopTileResources
Fullname   : C:\windows\DesktopTileResources
Size       : 21094
Count      : 17
Attributes : ReadOnly, Directory

Use the -Force parameter to include hidden directories.
.Example
PS C:\> get-foldersize c:\work | format-table -auto

Path               Name             Size Count Attributes
----               ----             ---- ----- ----------
C:\work            work        252083656   223  Directory
C:\work\atomic     atomic         622445     6  Directory
C:\work\fooby      fooby              18     1  Directory
C:\work\images     images        1470091   118  Directory
C:\work\resources  resources     8542561   143  Directory
C:\work\shell      shell          225161     4  Directory
C:\work\test       test         17198758     4  Directory
C:\work\Test Rig 2 Test Rig 2    4194304     1  Directory
C:\work\test2      test2              40     2  Directory
C:\work\Ubuntu12   Ubuntu12   7656701952     2  Directory
C:\work\widgets    widgets        162703    49  Directory

.Example
PS C:\> get-foldersize c:\users\jeff\ -force | out-gridview -title Jeff
.Notes
Last Updated: May 8, 2013
Version     : 0.9

  ****************************************************************
  * DO NOT USE IN A PRODUCTION ENVIRONMENT UNTIL YOU HAVE TESTED *
  * THOROUGHLY IN A LAB ENVIRONMENT. USE AT YOUR OWN RISK.  IF   *
  * YOU DO NOT UNDERSTAND WHAT THIS SCRIPT DOES OR HOW IT WORKS, *
  * DO NOT USE IT OUTSIDE OF A SECURE, TEST SETTING.             *
  ****************************************************************
.Link
http://jdhitsolutions.com/blog/2013/05/getting-top-level-folder-report-in-powershell
.Inputs
None
.Outputs
Custom object
#>

[cmdletbinding()]
Param(
[Parameter(Position=0)]
[ValidateScript({Test-Path $_})]
[string]$Path=".",
[switch]$Force
)

Write-Verbose "Starting $($myinvocation.MyCommand)"
Write-Verbose "Analyzing $path"

#define a hashtable of parameters to splat to Get-ChildItem
$dirParams = @{
Path = $Path
ErrorAction = "Stop"
ErrorVariable = "myErr"
Directory = $True
}

if ($hidden) {
    $dirParams.Add("Force",$True)
}
$activity = $myinvocation.MyCommand

Write-Progress -Activity $activity -Status "Getting top level folders" -CurrentOperation $Path

$folders = Get-ChildItem @dirParams

#process each folder
$folders | 
foreach -begin {
     Write-Verbose $Path
     #initialize some total counters
     $totalFiles = 0
     $totalSize = 0
     #initialize a counter for progress bar
     $i=0

     Try {     
        #measure files in $Path root
        Write-Progress -Activity $activity -Status $Path -CurrentOperation "Measuring root folder" -PercentComplete 0
        #modify dirParams hashtable
        $dirParams.Remove("Directory")
        $dirParams.Add("File",$True)
        $stats = Get-ChildItem @dirParams | Measure-Object -Property length -sum
     }
     Catch {
        $msg = "Error: $($myErr[0].ErrorRecord.CategoryInfo.Category) $($myErr[0].ErrorRecord.CategoryInfo.TargetName)"
        Write-Warning $msg
     }
     #increment the grand totals
     $totalFiles+= $stats.Count
     $totalSize+= $stats.sum

     if ($stats.count -eq 0) {
        #set size to 0 if the top level folder is empty
        $size = 0
     }
     else {
        $size=$stats.sum
     }

     $root = Get-Item -Path $path
     #define properties for the custom object
     $hash = [ordered]@{
         Path = $root.FullName
         Name = $root.Name
         Size = $size
         Count = $stats.count
         Attributes = (Get-Item $path).Attributes
         }
     #write the object for the folder root
     New-Object -TypeName PSobject -Property $hash

    } -process { 
     Try {
        Write-Verbose $_.fullname
        $i++
        [int]$percomplete = ($i/$folders.count)*100
        Write-Progress -Activity $activity -Status $_.fullname -CurrentOperation "Measuring folder" -PercentComplete $percomplete

        #get directory information for top level folders
        $dirParams.Path = $_.Fullname
        $stats = Get-ChildItem @dirParams -Recurse | Measure-Object -Property length -sum
     }
     Catch {
        $msg = "Error: $($myErr[0].ErrorRecord.CategoryInfo.Category) $($myErr[0].ErrorRecord.CategoryInfo.TargetName)"
        Write-Warning $msg
     }
     #increment the grand totals
     $totalFiles+= $stats.Count
     $totalSize+= $stats.sum

     if ($stats.count -eq 0) {
        #set size to 0 if the top level folder is empty
       $size = 0
     }
     else {
        $size=$stats.sum
     }
     #define properties for the custom object
     $hash = [ordered]@{
         Path = $_.FullName
         Name = $_.Name
         Size = $size
         Count = $stats.count
         Attributes = $_.Attributes
        }
     #write the object for each top level folder
     New-Object -TypeName PSobject -Property $hash
 } -end {
    Write-Progress -Activity $activity -Status "Finished" -Completed
    Write-Verbose "Total number of files for $path = $totalfiles"
    Write-Verbose "Total file size in bytes for $path = $totalsize"
 }

 Write-Verbose "Ending $($myinvocation.MyCommand)"
 } #end Get-FolderSize

The function defaults to the local path and gets a collection of all of the top level folders, that is, those found directly in the root. The function then takes the collection of folders and pipes them to ForEach-Object. Most of the time we only use the Process scriptblock with ForEach-Object, but I want to take advantage of the Begin and End blocks as well. In the Begin scriptblock I measure all of the files in the root of the parent path and create a custom object that shows the number of files and total size in bytes. I’m going to get this same information for each child folder as well.

The process scriptblock does just that for each top level folder. This version of my function uses Write-Progress to display progress and in the End script block I have code to complete the progress bar, although It works just fine without it.

Other techniques I’d like to point out are the use of splatting and error handling. You’ll notice that I’m using the common -ErrorVariable parameter. After exploring the different types of exceptions I decided I could easily display any errors and the paths In the Catch block. I’m using Write-Warning, but this could just as easily be written to a text file.

The function writes an object like this for every folder.

Path       : C:\windows\Inf
Name       : Inf
Size       : 81926300
Count      : 1265
Attributes : Directory

Here’s an example of complete output:

Because I’ve written objects to the pipeline, I could pipe this to Out-Gridview, export to a CSV file or create an HTML report.

This is just a taste of what you can accomplish with some basic PowerShell commands.

#requires -version 2.0

Function New-Messagebox {

<#
.Synopsis
Display a VisualBasic style message box.
.Description
This function will display a graphical messagebox, like the one from VisualBasic
and VBScript. You must specify a message. The default button is OKOnly and the 
default icon is for Information. If you want to use the value from a button click
in a PowerShell expression, use the -Passthru parameter.

The message box will remain displayed until the user clicks a button. The box may 
also not appear on top, but if you have audio enabled you should hear the Windows 
exclamation sound.
.Parameter Message
The text to display. Keep it short.
.Parameter Button
The button set to display. The default is OKOnly. Possible values are:
    OkOnly
    OkCancel
    AbortRetryIgnore
    YesNoCancel
    YesNo
    RetryCancel
.Parameter Icon
The icon to display. The default is Information. Possible values are:
    Critical
    Question
    Exclamation
    Information
.Parameter Title
The message box title. The default is no title. The title should be less than 
24 characters long, otherwise it will be truncated.
.Parameter NoPassthru
Use this parameter if you DO NOT want the button value to be passed to the pipeline.
.Example
PS C:\> New-Messagebox "Time to go home!"
Display a message box with no title and the OK button.
.Example
PS C:\> $rc=New-Messagebox -message "Do you know what you're doing?" -icon exclamation -button "YesNoCancel" -title "Hey $env:username!!" 
Switch ($rc) {
 "Yes" {"I hope your resume is up to date."}
 "No" {"Wise move."}
 "Cancel" {"When in doubt, punt."}
 Default {"nothing returned"}
}
.Example
PS C:\> New-MessageBox -message "Are you the walrus?" -icon question -title "Hey, Jude" -button YesNo
.Inputs
None
.Outputs
[system.string]
#>

[cmdletbinding()]

Param (
[Parameter(Position=0,Mandatory,HelpMessage="Specify a display message")]
[ValidateNotNullorEmpty()]
[string]$Message,
[ValidateSet("OkOnly","OkCancel","AbortRetryIgnore","YesNoCancel","YesNo","RetryCancel")]
[string]$Button="OkOnly",
[ValidateSet("Critical", "Question", "Exclamation", "Information")]
[string]$Icon="Information",
[string]$Title,
[switch]$NoPassthru
)

#load the necessary assembly
Try { 
    Add-Type -AssemblyName "Microsoft.VisualBasic" -ErrorAction Stop     
    #create the message box using the parameter values
    $returnValue = [microsoft.visualbasic.interaction]::Msgbox($message,"$button,$icon",$title)
}
Catch {
    Write-Warning "Failed to add Microsoft.VisualBasic assembly or create the messagebox."
    Write-Warning $error[0].Exception.Message
}
#do not write return value if -NoPassthru is called
if (-Not $NoPassthru) {
    Write-Output $returnValue
}

} #end function

Most of the function is a wrapper around this line:

$returnValue = [microsoft.visualbasic.interaction]::Msgbox($message,"$button,$icon",$title)

Like the popup function, I wanted to make it easier to create a messagebox without having to remember the names for buttons and icons so I use validation sets with my parameters. This makes it much easier to create a command like this in your script:

New-Messagebox -Message "Do you want to delete the files?" -Button YesNoCancel -Icon Question -Title "Are you sure?"

In the version I presented at the PowerShell Summit, the function did not write anything to the pipeline unless you used -Passthru. After thinking about it more, I realized the whole reason you are likely to use a MessageBox is to capture an interaction so I flipped the parameter and now it is -NoPassthru. Now, when the user clicks a button, the text value of that button is automatically written to the pipeline. If you include -NoPassthru you’ll get nothing. Here’s an example:

$ask = New-Messagebox -Message "Do you want to delete all objects in Active Directory?" -Button YesNo -Icon Exclamation -Title "What are you thinking?"
if ($ask -eq "yes") {
 Write-Host "Updating resume..." -ForegroundColor Red
 #evil code
}
else {
 Write-Host "Sanity restored" -ForegroundColor Green
}

Because the messagebox writes text to the pipeline, it is a little easier to use than the Popup technique where you have to decode an integer value. In any event, you now have some options.

If you find this useful, I hope you’ll let me know.

Here’s an example.

$c=0
While ($c -le 5) {
 $c
 $c++
}

If you run this, you’ll see numbers 1 to 5 written to the pipeline. But if you try something like this it will fail.

$c=0
While ($c -le 5) {
 $c
 $c++
} | out-file foo.txt

You’ll get an error about an empty pipe. In fact, in the PowerShell ISE you’ll get a red squiggle under the | indicating this is not going to work. That’s because PowerShell isn’t writing to pipeline at the end of the scriptblock, but rather within in. Another way to think about it is at the While operator is not a cmdlet so the only thing writing objects to the pipeline is whatever commands are within the While loop.

What you can do is something like this:

$c=0
$a = While ($c -le 5) {
 $c
 $c++
} 
$a | out-file foo.txt

Here, I’m capturing the pipeline output from the scriptblock and saving it to a variable. Then I have objects I can use. Or if you wanted to be clever, you could use a subexpression.

$c=0
$(While ($c -le 5) {
 $c
 $c++
}) | get-member

This same behavior also applies to Do and the ForEach enumerator. The latter trips people up all the time.

$i=1..5
foreach ($x in $i) {
  $x * 2
} | out-file results.txt

You think you’ll get the output of ForEach saved to the file, but you’ll run into the empty pipeline again. You could use a variable and then pipe the variable to the file or use a subexpression. Even better, use a pipelined expression.

1..5 | foreach {$_*2} | out-file results.txt

Here I’m using the cmdlet ForEach-Object, which unfortunately has an alias of ForEach which confuses PowerShell beginners. So don’t assume that just because you see a set of { } that you get pipelined output. Remember, cmdlets write objects to the pipeline, not operators.

File and Folders with Powershell 3
If you manage file servers and aren’t using PowerShell, you are working much too hard. Or if you are using PowerShell v2 you are still working pretty hard. Fortunately PowerShell v3 along with Windows 8 and Windows Server 2012 offer a much better solution. This session will demonstrate how to provision and manage folders, files and file shares using PowerShell from a Windows 8 client. With a little up-front work, you ‘ll be able to create provisioning scripts to deploy a new file share in seconds.

10 PowerShell mistakes, trip-ups and traps
Windows PowerShell is a language and management technology that many IT professionals, including developers, think they understand. Yet very often they get caught up in pre-conceptions and misinterpretations, usually based on prior experience with scripting or development. This session will explore the 10 most common mistakes and traps that people fall into with PowerShell and how to avoid them.

Troubleshooting Active Directory with PowerShell
Active Directory is one of those technologies that when it works, nobody notices. But when it doesn’t work, everyone does. Fortunately, Windows PowerShell and Windows Server 2012 make a terrific troubleshooting tool. In this session we’ll look at some common Active Directory problems, how to diagnose them and in some cases resolve, all with Windows PowerShell.

Building a Windows 8 Hyper-V lab
We all know the benefits of testing in a non-production environment. But sometimes resources are limited and having a test setup seems like a lot of work. But now that Windows 8 includes Hyper-V, you can setup a lab environment in very little time. This session will guide you through setting up a Hyper-V based test lab and how to get the most out of it using the PowerShell management tools.

If you didn’t catch me in San Francisco, I’ll be at TechMentor this fall in Las Vegas. More on that later. There’s a chance I’ll be back to the West coast later this year for more PowerShell goodness. Keep an eye on the blog for announcments. Or if your company is looking for training, let’s talk.

All it really takes is two lines. One line to create the Wscript.Shell COM object and one to invoke the Popup method.  (Yes, I’m sure you could do this in one line, but that’s not the point.)

$wshell = New-Object -ComObject Wscript.Shell -ErrorAction Stop
$wshell.Popup("Are you looking at me?",0,"Hey!",48+4)

The Popup method needs parameters for the message, title, a timeout value, and an integer value that represents a combination of buttons and icons.

The challenging part has always been trying to remember the integer values. So I wrote a quick function called New-Popup.

#requires -version 2.0

Function New-Popup {

<#
.Synopsis
Display a Popup Message
.Description
This command uses the Wscript.Shell PopUp method to display a graphical message
box. You can customize its appearance of icons and buttons. By default the user
must click a button to dismiss but you can set a timeout value in seconds to 
automatically dismiss the popup. 

The command will write the return value of the clicked button to the pipeline:
  OK     = 1
  Cancel = 2
  Abort  = 3
  Retry  = 4
  Ignore = 5
  Yes    = 6
  No     = 7

If no button is clicked, the return value is -1.
.Example
PS C:\> new-popup -message "The update script has completed" -title "Finished" -time 5

This will display a popup message using the default OK button and default 
Information icon. The popup will automatically dismiss after 5 seconds.
.Notes
Last Updated: April 8, 2013
Version     : 1.0

.Inputs
None
.Outputs
integer

Null   = -1
OK     = 1
Cancel = 2
Abort  = 3
Retry  = 4
Ignore = 5
Yes    = 6
No     = 7
#>

Param (
[Parameter(Position=0,Mandatory=$True,HelpMessage="Enter a message for the popup")]
[ValidateNotNullorEmpty()]
[string]$Message,
[Parameter(Position=1,Mandatory=$True,HelpMessage="Enter a title for the popup")]
[ValidateNotNullorEmpty()]
[string]$Title,
[Parameter(Position=2,HelpMessage="How many seconds to display? Use 0 require a button click.")]
[ValidateScript({$_ -ge 0})]
[int]$Time=0,
[Parameter(Position=3,HelpMessage="Enter a button group")]
[ValidateNotNullorEmpty()]
[ValidateSet("OK","OKCancel","AbortRetryIgnore","YesNo","YesNoCancel","RetryCancel")]
[string]$Buttons="OK",
[Parameter(Position=4,HelpMessage="Enter an icon set")]
[ValidateNotNullorEmpty()]
[ValidateSet("Stop","Question","Exclamation","Information" )]
[string]$Icon="Information"
)

#convert buttons to their integer equivalents
Switch ($Buttons) {
    "OK"               {$ButtonValue = 0}
    "OKCancel"         {$ButtonValue = 1}
    "AbortRetryIgnore" {$ButtonValue = 2}
    "YesNo"            {$ButtonValue = 4}
    "YesNoCancel"      {$ButtonValue = 3}
    "RetryCancel"      {$ButtonValue = 5}
}

#set an integer value for Icon type
Switch ($Icon) {
    "Stop"        {$iconValue = 16}
    "Question"    {$iconValue = 32}
    "Exclamation" {$iconValue = 48}
    "Information" {$iconValue = 64}
}

#create the COM Object
Try {
    $wshell = New-Object -ComObject Wscript.Shell -ErrorAction Stop
    #Button and icon type values are added together to create an integer value
    $wshell.Popup($Message,$Time,$Title,$ButtonValue+$iconValue)
}
Catch {
    #You should never really run into an exception in normal usage
    Write-Warning "Failed to create Wscript.Shell COM object"
    Write-Warning $_.exception.message
}

} #end function

The function lets you use text descriptions for the buttons and icons. In PowerShell 3.0 you will also get tab completion for the possible values. This makes it easy to create a command like this:

new-popup "Do you want to get work done with PowerShell?" -Title "Hey, you!" -Buttons YesNo -Icon Question

The function writes the value of the clicked button to the pipeline. I expect this is something you are more apt to use in a script. Perhaps to display an error message or even to prompt the user for an action. Maybe you’d like to use it in your PowerShell 3.0 profile:

$r = New-Popup -Title "Help Update" -Message "Do you want to update help now?" -Buttons YesNo -Time 5 -Icon Question
if ($r -eq 6) {
  Update-Help -SourcePath \\jdh-nvnas\files\PowerShell_Help -Force
}

The popup will automatically dismiss after 5 seconds unless I click Yes or No. You should be able to copy the function text from the listing above by toggling to plain code, select all and copy.

I hope you’ll let me know where you use this.