Two Point Conversion

A week after I finished my last post about converting variables between data types I ran into a problem converting data types that wasn't covered by anything in the post.  Time for one more play.

In my case I needed to add a new value to the registry.  The data is different for each host and the input file lists the data values as a hexadecimal string.  The type accelerators for numeric conversion don't help in this case

How to crack that nut?  When in doubt, check if .net has any tools for us to use.  In this case there is a quite powerful system class named, appropriately enough, convert.  This is the swiss army knife of data conversion letting us convert just about any concievable combination of data classes.

In my case I needed to use one of the ToInt methods.  Registry values will be either 32 or 64 bit (dword or qword) but 64 bit will only work with newer versions of Windows.

Notice how many different possible inputs I have for ToInt32.  The one I need is the one that accepts a string and specifies the base of the string.  There are versions of this for 16 and 64 bit integers as well.   This example shows the string '1010' converted from the available bases, binary, octal, decimal, and hexadecimal.

Most of the conversion methods are straightforward and self explanitory.  The ToByte method could have worked if the hex values were small enough to fit into a single byte.

ToBoolean converts any number isn't a zero to true.  And it can interpret any string that evaluates to 'true' or 'false'.  This would be handier if it could automatically convert numeric strings to numbers or evaluate logical equivilants like 'yes' or 'no' to 'true' or 'false'.

The ToBase64 and FromBase64 methods allow some quick encoding and decoding of strings and character arrays.  Depending on the input you may have to do some massaging of the data because the ToBase64 method expects an array of bytes as input.

The GetTypeCode returns a value describing the data type of the input object.

This information comes in handy if you want to use the ChangeType method.

But that's a long way to go because we have the shortcut of using the type accelerators.  You will almost always use the built-in type accelerators but, as in dating, its nice to know you have other options.

Not my type

In programming languages variables can be of a specific data type, such as integers or strings of characters.  If a language requires variable to be defined as containing only a specific class of data it is called strongly typed.  If the variables can contain any kind of data the language is weakly typed.  If the language is experimental it is prototyped. If it requires punch cards it is teletyped

http://www.staff.ncl.ac.uk/roger.broughton/museum/iomedia/images/pc6.jpg

As mentioned previously, everything in PowerShell is an object.  But simple scalar variables still have a data type.  PowerShell makes a best guess at what the type should be and does conversions on the fly so you usually don't have to worry about the data type of a variable or performing explicit conversions.

Here PowerShell converts the string to an integer, multiplies it with the floating point number, then adds the hexadecimal number.  When I give the answer it converts the integer to a string so it can be concatenated with the rest of the text.

Most of the time PowerShell correctly determines the data type and formats the output accordingly.  But what if you need to force a variable to be a specific type?  Precede either the variable or expression with the .NET value type enclosed in square brackets.  In this example we divide two numbers and cast the result as an integer and string respectively.

But that looks like it involves a bunch of typing.  Wouldn't it be nice if there was a shortcut to access those system types?  Yes it would be nice so that's why the nice people who made PowerShell included some type accelerators.  Instead of using [System.Int32] I can use [int] and instead of [System.String] I can use [string]

Are there many of these type accelerators available?  Yes there are. Oisen Grehan 's blog post not only shows all of the accelerators available but a handy way to list them all.  One that does not show up in the list is the [DateTime] accelerator for [System.DateTime].  Notice how flexible this value type is.

Now go back and check Oisen Grehan's blog post again.  There's all kinds of useful stuff that is just as flexible as the [DateTime] accelerator.  For example, there is the [ipaddress] data type that accepts a string and converts it to an IP address.

This is pretty sweet.  Notice that the type accelerator processes both IPv4 and IPv6 addresses.  If I need to prompt my user for an IP address I don't need to parse and validate it.  I can just assign it to a variable that has the [ipaddress] type and wrap it with some error handling then let .Net and PowerShell do the heavy lifting.

One other handy accelerator is the array type.  Why is it handy?  Because it gives us access to all of the methods for the .Net array class.  To access any of the .Net class methods specify the class in square brackets followed by two colons and then the method.

Note that that when calling these methods they only operate on the variable you pass.  If you need to keep the array in its original state you need to copy it first and then call the method on the copy.

Type accelerators are one of PowerShell's many useful and time saving capabilities.  If you never introduce yourself you might not know that PowerShell is just your type.

The Power of Failure

Wow.  It's been a while since my last post.  I was... delayed.

If you ever bought a house and had to deal with bankers, brokers, realtors, contractors, movers, utilities, inspectors, insurance agents, lawyers, and sundry government agencies, you realize this is kind of how it is.

But let's deal with a different type of failure.  Powershell uses ErrorAction to define how a script responds to errors.  This can be defined globally by assigning a value to the $ErrorActionPreference variable.  You can override default behavior for a specific cmdlet by using the -ErrorAction common parameter.  Possible values are Stop, Inquire, Continue, and SilentlyContinue.  These are explained in the snippet from help about_preference_variables.

Note that the default ErrorAction is actually Continue, not SilentlyContinue as stated in the help.  You can see examples of these settings by issuing the help about_preference_variables and help about_commonparameters commands.  As I debug scripts I set the $ErrorActionPreference to Inquire or Continue.  But once I put error handling in place I set it to SilentlyContinue.

What can I do to evaluate errors?  One way is to check the value of the variable $?.  This is set to $True if the previous command completed successfully and $False if it failed.  The variable $LastExitCode has the value of the exit code for the most recently executed command.  These variables give me all the power I need to simulate a DOS batch file, if that's what you need to do.

But wait, there's more!

If an error is raised the information about it gets added to the $Error variable.  $Error can be referenced like an array but it is actually a circular buffer with a default length of 256.  Once your script generates the 257th error the first error gets deleted to make room for the new error.  If you really want to keep more more than 256 errors you can set the $MaximumErrorCount variable.  The most recent error is referenced as $Error[0].  The $Error buffer can be cleared by using the $Error.Clear() method.  So now I have all the power I need to simulate a vbScript, not that there's anything wrong with that.

But wait, there's more!

PowerShell lets us create a trap.  This is a block of code that gets executed whenever an error is raised so you don't have to check for errors at each critical step.  If you need to raise an error use the Throw command.  Use the Continue command in the trap block to keep processing the rest of the script or use the Break command to exit the current block of code.

 

Traps only work inside scripts so don't use them in an interactive session.  If you don't include the Continue command at the end of the trap block then PowerShell will still display the default error message in red text in addition to the tasks in the trap.  Traps are scope aware so you can use different traps inside user defined functions.  In the following example the trap inside the function does not trigger the global trap that is outside the function.

You can specify different traps for different types of exceptions.  For example you might have one trap that deals with file system errors and another that deals with network errors.  The powershell.com guys do a good job of explaining this and other intricacies.  Joel Bennet explores other anomalies.

But wait, there's more!

With PowerShell 2.0 and beyond we have the try-catch-finally construct used in modern object oriented languages.  This not only gives you a sweet way to methodically handle errors but also lets you break the script into logical chunks and use the Write-Progress cmdlet to show users how close we are to completion.

And like the Trap, you can have different Catch blocks for different types of errors.  In the first section of the previous example where I read the data, I could have one catch block if the file is not found, another catch block if I can't read the file, and another as a catch all catch to catch whatever else I didn't catch:

Try {
    # Read the data
}
Catch [System.IO.FileNotFoundException] {
    echo "The file wasn't found"
    break
}
Catch [System.IO.IOException] {
    echo "The file could not be opened"
    break
}
Catch {
    echo "An unexpected error happened.  Check the Mayan calendar."
    break
}

As usual, most of these examples are stupid.  If all you do is tell the user that an error happened you don't need any of these facilities.  Just let PowerShell show the default error message and take the appropriate ErrorAction.  The real power in error handling is to take corrective action: prompt the user for a file that exists, fix the input so it has the correct format, reset a failed network connection, cast the ring of power into the fires of Mount Doom, etc.

Remember, failure is a natural and happens all the time.  Recovering by turning failure into success is what error handling is all about.  PowerShell has abundant tools to help you achieve that goal.

Did I do that?

In one of my first college computer science classes the professor asked the question, "Half of your code should be what?"  To which I replied, "functioning".  The professor wasn't amused but I wasn't far off.  The answer he was looking for was error handling.  Anybody can program a tic-tac-toe game but a well written game will give the user useful information when they try to input something other than an X or O.

http://www.kellie.de/jw1/steve4.jpg

If I am writing a script that only I will use then I won't bother with adding error handling.  In those cases I usually leave all output turned on so if an error arises I can see and troubleshoot it.  But if a script will be used by others I try to make it as friendly as possible.

When I first started writing DOS batch files the only error handling was through the IF ERRORLEVEL command.  ERRORLEVEL is populated with the return code from the previous command.  The return code is zero if the command completed successfully and something else if it failed.  IF ERRORLEVEL evaluates to TRUE if the ERRORLEVEL is greater than or equal to the value supplied.  So error handling in batch files consisted of a bunch of IF statements with the known ERRORLEVELs and associated GOTO statements.

IF ERRORLEVEL 10 GOTO Error10
IF ERRORLEVEL 5  GOTO Error5
IF ERRORLEVEL 1  GOTO Error1
GOTO Success

:Error10
ECHO You got your peanut butter in my chocolate
GOTO Success

:Error5
ECHO You got your chocolate in my peanut butter
GOTO Success

:Error1
ECHO I don't have chocolate or peanut butter

:Success
ECHO And now I'm hungry

Batch file processing has improved over the years.  You can still use the IF ERRORLEVEL statement but if you have command extensions enabled then ERRORLEVEL is also an environment variable.  The first three lines in the previous script could be reduced to the single line:

IF ERRORLEVEL 1 GOTO Error%ERRORLEVEL%

Also the IF statement is now more robust and allows for standard numerical comparisons as well grouping multiple commands in parentheses.

IF %ERRORLEVEL% EQU 10 (
    ECHO You got your chocolate in my peanut butter
) ELSE (
IF %ERRORLEVEL% EQU 5 (
    ECHO You got your peanut butter in my chocolate
) ELSE (
IF %ERRORLEVEL% GEQ 1 (
    ECHO I don't have chocolate or peanut butter
)))
ECHO And now I'm hungry

Those are stupid examples.  You have capabilities to not only provide user feedback, but to retry failed operations, solicit input from users, or enable other resolutions.  Still, the facilities are rudimentary.

In vbScript the facilities improve.  vbScript error handling starts with the On Error statement which defines whether error handling is on or off.  On Error Goto 0 turns off internal error handling and lets your script fail on error.  On Error Resume Next turns on error handling and enables the internal Err object.  This object contains the error number as well as descriptive information.

On Error Resume Next

' Do something useful here
If Err.Number <> 0 Then
    WScript.Echo "Error: " & Err.Number
    WScript.Echo "Source: " &  Err.Source
    WScript.Echo "Description: " &  Err.Description
    Err.Clear
End If

Note that we clear the error after reporting it.  If the Err object doesn't get cleared then our next test of Err.Number might report the previous error.

This generic error handling can be enclosed in a user defined function and called for each error detected.

On Error Resume Next

' Do something useful
If Err > 0 Then
        DisplayErrorInfo
End If

' Do something else useful
If Err > 0 Then
        DisplayErrorInfo
End If

Sub DisplayErrorInfo
    WScript.Echo "Error:      : " & Err
    WScript.Echo "Source      : " & Err.Source
    WScript.Echo "Description : " & Err.Description
    Err.Clear
End Sub

If you know which error codes are returned by the application being called then you can do something more elegant than just return generic error information.  Here is some code pinched from The Scripting Guys.

On Error Resume Next

strComputer = "."

arrTargetProcs = Array("calc.exe","freecell.exe")

Set objWMIService = GetObject("winmgmts:" _

 & "{impersonationLevel=impersonate}!\\" & strComputer & "\root\cimv2")

For Each strTargetProc In arrTargetProcs

    Set colProcesses = objWMIService.ExecQuery _

      ("SELECT * FROM Win32_Process WHERE Name='" & strTargetProc & "'")

    If colProcesses.Count = 0 Then

        WScript.Echo VbCrLf & "No processes named " & strTargetProc & " found."

    Else

        For Each objProcess in colProcesses

            WScript.Echo VbCrLf & "Process Name: " & objProcess.Name

            Wscript.Echo "Process ID: " & objProcess.Handle

            Wscript.Echo "Attempting to terminate process ..."

            intTermProc = TerminateProcess(objProcess)

        Next

    End If

Next

'***********************************************************************

Function TerminateProcess(objProcess)

    On Error Resume Next

    intReturn = objProcess.Terminate

    Select Case intReturn

        Case 0 Wscript.Echo "Return code " & intReturn & _
                " - Terminated"

        Case 2 Wscript.Echo "Return code " & intReturn & _
                " - Access denied"

        Case 3 Wscript.Echo "Return code " & intReturn & _
                " - Insufficient privilege"

        Case 8 Wscript.Echo "Return code " & intReturn & _
                " - Unknown failure"

        Case 9 Wscript.Echo "Return code " & intReturn & _
                " - Path not found"

        Case 21 Wscript.Echo "Return code " & intReturn & _
                " - Invalid parameter"

        Case Else Wscript.Echo "Return code " & intReturn & _

                " - Unable to terminate for undetermined reason"

    End Select

    TerminateProcess = intReturn

End Function

Something else to note is that the Err object has the method Raise which allows you to generate an error on demand.  This is useful for debugging error handling code or if you just want to punk your users.  It is also useful if you need to pass errors to other modules.  Note that you have to add the constant vbObjectError to the error number you want to raise to prevent collision with existing errors.

In the next post I will discuss error handling in PowerShell.  In case you couldn't guess, it is far superior to DOS and vbScript.

Splat in the Hat

In PowerShell the @ character is called the splat operator.  I'm still trying to figure out why it is called splat.

I'm pretty sure that's not why.  Nevertheless the splat operator has many uses in PowerShell.

In a previous post I demonstrated using the splat operator to create a custom object.

$X = New-Object PSObject -Properties @{
     Name="ObjectName";
     SomeValue=1;
     AnotherValue=10
}

The splat operator is also used to define an array.

$Array = @("one","two","three","four")

PowerShell is forgiving and will let you define an array without the splat operator.

$Array = "one","two","three","four"

But if you need to force the results to be an array you can use the splat operator.  I frequently do this if I'm creating an array of custom objects.  I first define an empty array, then fill it with the objects.

$Procs = @()
foreach ($P in (get-process | get-unique)) {
   $New = New-Object PSObject -Property @{
      Name=$P.ProcessName;
      Company=$P.Company;
      Product=$P.Product;
      Version=$P.ProductVersion
   }
   $Procs += $New
}
$Procs

The splat operator can also be used to force the results of a command into an array.  Enclose the command or cmdlet in parentheses and precede the opening parenthesis with the splat operator.

In the above example the variable $X has a length of 843 because it measures the length of the string returned by the Dir command.  $Y and $Z have a length of 1 because it is the length of the array.  The length of the first and only element of those single element arrays matches the length of the string $X.  I included the variable $Z to show another way of forcing a variable to be an array.

The splat operator is also used to create hash tables.  Hash tables are similar to dictionary objects in VBScript but are much more versatile.  A basic hash table lets you add and remove members in addition to doing searches.  To create the hash table start with the splat, enclose the table in curly braces, and separate items with semi-colons.

$Meals = @{"Breakfast"="Eggs";"Lunch"="Sandwich";"Supper"="Chicken"}

Another use for hash tables (and by association our friend the splat operator) is to define a group of parameters for cmdlets.  In this use the keys are the named parameters and the values are the input for the parameters.

Notice that when the hash table is used to provide parameters to the cmdlet the variable name is preceded with the splat operator instead of the dollar sign.  This tells PowerShell to process the variable as a hash table and use the keys and values as parameters to the cmdlet.

This technique is really useful for making code more readable.  The cmdlet Write-EventLog lets you add records to the Windows event logs.  In the example below I use the source WSH because its events have free form messages which allows me to use Get-WinEvent to confirm the results.

Write-EventLog -LogName Application -Source WSH -EventID 0 -EntryType Information -Message "I added this to the event log from PowerShell"

That works but the Write-EventLog cmdlet gets cumbersome with all of the parameters on a single line.  If I splat the parameters in a hash table the code becomes much easier to read and costs very little extra typing.

$ELParams = @{
    'LogName' = 'Application';
    'Source'  = 'WSH';
    'EventId' = 0;
    'EntryType'= 'Information';
    'Message' = 'I splatted this to the Application log using PowerShell'
}
Write-EventLog @ELParams

Note that while I hard coded all of the parameter names and values in the hash table I could just as easily use variables for any of them.  This allows for some sophisticated processing inside loops and user defined functions.

One final use for the splat operator is the Here-String.  A Here-String is PowerShell's facility for specifying a large block of text that spans multiple lines.  Start the bock of text with the splat and quote @" and end the block with a quote and splat "@.  (On a personal note "Quote and Splat" is the law firm who handled my divorce settlement.)  Inside the Here-String you can specify line breaks and include quotes and other special characters.  The Here-String will display just as you specified.

The splat operator gives us a variety of shortcuts to keep our code efficient and tidy.  But remember that with great power comes great responsibility.  So remember to splat wisely, unlike this juvenile.

Commentors:  Seriously, does anybody know why they call it splat?

A good time

Time is what keeps everything from happening all at once.  I think Confucius said that.  Or maybe it was one of those stoner guys I met at college.  Either way most humans agree that time is frequently useful.

Sometimes you need to know how long it takes a script to run.  This comes in handy if you are comparing various techniques to accomplish a task and want to find the most efficient approach.  Or if you need to benchmark a script with a small data set to estimate how long it will take with the full data set.  Or maybe you are just curious like a cat.

vbScript has the function Time that returns the (you guessed it) current system time.  It is returned as a datetime value so use the DateDiff function to compare the difference between two values.  My sample script is:

StartTime = Time
wscript.echo StartTime

for i = 1 to 100000000
next

EndTime = Time
wscript.echo EndTime

TotTime = DateDiff("s",StartTime,EndTime)wscript.echo TotTime

wscript.echo "The operation took " + cStr(TotTime) + " seconds."

The Time and DateDiff functions only offer time accurate to the second.  Instead we should use the Timer function.  This not only offers greater accuracy but it also lets us do simple math to see the results.

StartTime = Timer
wscript.echo StartTime

for i = 1 to 50000000
next

EndTime = Timer
wscript.echo EndTime

TotTime = cStr(EndTime-StartTime)
wscript.echo "The operation took " + TotTime + " seconds."

The DOS environment variable %TIME% is accurate to the hundredth of a second.  You can use this if you want to time the processing of a batch file, but you have to do some serious parsing of the variable by using the FOR command.  In this example I use FOR /F to break the %TIME% string into 4 pieces (hours, minutes, seconds, hundredths) and do a bunch of math to turn the whole thing into the number of hundredths of seconds since midnight.  (The two FOR /F commands are wrapped in the example below.)

echo OFF
echo %TIME%
for /F "tokens=1-4 delims=:." %%A in ('echo %TIME%') do set /A Start=(%%A*60*60*100)+(%%B*60*100)+(%%C*100)+%%D

for /L %%X in (0,1,10000) do rem

for /F "tokens=1-4 delims=:." %%A in ('echo %TIME%') do set /A Stop=(%%A*60*60*100)+(%%B*60*100)+(%%C*100)+%%D
ECHO ON

set /A TotTime=%Stop%-%Start%
set /A Secs=%TotTime%/100
set /A Hund=%TotTime% %% 100
echo "The operation took %Secs%.%Hund% seconds"

set Hund=0%Hund%
set Hund=%Hund:~-2%
echo "The operation took %Secs%.%Hund% seconds"

The math is pretty straightforward and I can calculate the elapsed time with simple subtraction.  I use the modulo operator (%) to separate hundredths from seconds.  But note that the environment variables are strings, so I still need to add a leading zero then take the last 2 characters of the string to make sure I have a 2 digit integer after the decimal point.

But PowerShell is the undisputed champ of scripting and and timing script execution is no exception.  Sure, there are cmdlets for finding the current time and methods for doing datetime math.  But why go to all that trouble when you have the Measure-Command cmdlet?  Enclose the code you need to benchmark in brackets and PowerShell gives you detailed timing information.



As always, the cmdlet returns an object that you can process through the pipeline.  Here I use the shortcut of finding just the number of seconds it took to run the code.

If you have plenty of time then you have time to kill. But if you are out of time you are out of luck. So don't take your time for granted unless you are granted more time, in which case you can take all the time you need.  So until next time, take your time and take care.

The shortest distance

Everybody likes shortcuts.  If you can save yourself some time and effort, why not take the opportunity?

Powershell offers several ways to save yourself some typing and shorten your command lines and scripts.  Plus you almost never blow yourself up.

One way is to string together all of the slicing and dicing you might need to do.  If a method for an object returns an array and I know I need a specific element in that array I can specify that element  right after the method invocation.  And I can call a method right from that array element.  Allow me to demonstrate.

In a previous example I had to parse the DistinguishedName for a user.  I model my test domain based on a former employer who managed users and computers by location.  Delegations were done so support staff at each site could manage their objects.  My OU structure looks like this:

In order to find the site name for an arbitrary user account I can assign a variable at each step to parse the DistinguishedName.  In this example I also show the value of the variables to confirm each step:

But I don't need to use all those variables.  This can be processed in a single line.  Below I build up each step.  The last line shows how I combine all of these steps into a single command:

Another handy shortcut is to enclose a command in parentheses and do the same slicing and dicing.  In the above example I don't even need to assign the Get-ADUser output to a variable.  I can use the command
 (Get-ADUser AlAlpha).DistinguishedName.split(',')[2].substring(3)

Letting PowerShell process things in parentheses has many uses and works for all cmdlets.  You can nest some really crazy crap and it will still work.  In the following example I know I have a user in Atlanta with the last name Alpha and I'm not sure what the account name is but I have to change his first name to Allen.  The first command get-aduser -searchbase "OU=Atlanta,OU=Locations,DC=toddp,DC=local" -filter * | where {$_.surname -eq 'Alpha'} shows how I can do this search.  In the second command I enclose that first command in parentheses and use that as the identity for my Set-ADUser command.  I call Get-ADUser one last time to show the change was made in the GivenName attribute.

Another PowerShell shortcut is to use aliases for the cmdlets. 

Here we see all of the aliases that start with the letter "g".  Two aliases I use frequently are gm for Get-Member and gwmi for Get-WmiObject.


In this example the Get-ADUser output is piped through the Get-Member cmdlet using the alias GM.

You can create your own aliases using the Set-Alias cmdlet.

After using Import-Module (or its alias, ipmo) to import the ActiveDirectory cmdlets I use Set-Alias to create the alias gadu for the Get-ADUser command.  Note that an alias can only be for a cmdlet, not a cmdlet and its parameters.  You can work around this limitation by using a function as shown in the last example for Set-Alias.

There are two other aliases that you may encounter.

There is a default alias for ForEach-Object which is the percent sign (%) and an alias for Where-Object which is the question mark (?).  This will come in handy.

How cool is this?  I pipe Get-Process through the ForEach-Object shortcut to pull out the ProcessName and use the Where-Object shortcut to show just the processes starting with the letter "c".  That's good enough for me.

In Powershell 3 there is an implied ForEach-Object for arrays.  Instead of piping the array through ForEach-Object cmdlet or shortcut you just enclose the object in parentheses and process the properties you need.

These are the processes running on my Windows 8 demo VM.  But if I need to grab just the process name I can use the syntax (Get-Process).ProcessName

Pretty sweet.  There are some other handy shortcuts coming in PowerShell 3.

So we have all these nice shortcuts.  Shouldn't we use them all the time?  The rule of thumb from our friend Don Jones is that if you are writing a quick and dirty command for yourself, then the shortcuts can save you time and effort.  But scripts with shortcuts look more cryptic and are harder to read.  So if you are creating a more invovled script that will be used by someone else you should be considerate and make it more accessible by avoiding shortcuts. 

Knowing these shortcuts and aliases (or at least how to find what is being aliased) helps you be more efficient.  And if you come across a script written by someone else who used them you won't be caught off guard.