Execute-Remotely

One of the really powerful features of PowerShell is the ability to run commands remotely.  I used this when I wanted to loop through my test servers from the build machine and run my MSI installs.

The following script loops through an array of machines and returns a list of .log files under the C:\Windows folder.  One thing to note.  The remote session doesn't have access to any of the local script variables, so we pass them as parameters using the -Args argument of the Invoke-Command cmdlet, receiving them using the param statement inside the remote script block.

    $AgentServers = @("MYSERVER1", "MYSERVER2");
   
    ForEach ($AgentServer in $AgentServers) {
        $Session = New-PSSession -ComputerName $AgentServer;
        $FilePattern = "*.log";
        $Arguments = $FilePattern
        Invoke-Command -Session $Session  -Args $Arguments -Script {
            param($FilePattern)

            Set-Location "C:\Windows"
            Get-ChildItem -Include $FilePattern -Recurse
        }
        Remove-PSSession -Session $Session
    }                                                                                                    

Now the first time you run the remote script above, it may well fail. Why? Because you forgot to enable remoting on the target machine. On each machine you want to run remote sessions on you’ll have to run:

Enable-PSRemoting

Note that you’ll have to start PowerShell as administrator to perform this.

Also take note that we’re killing each session using Remove-PSSession when we’re done with it as there is a 5 session limit on each remote server and it’s pretty easy to hit that if you forget to close out prior ones.

On that note, there’s a quick trick on clearing out all those orphaned sessions:

Get-PSSession | Remove-PSSession

Get-PSSession will return a list of all open session objects, piping them to Remove-PSSession which subsequently closes them out.

Run-Script

As I mentioned in an earlier post, just like the DOS command line has batch files, PowerShell can run PowerShell script files.  These have the .PS1 extension.

So go ahead, throw a bunch of PowerShell commands together into a .PS1 file in NotePad and save it.  Next, navigate to the folder you saved it to and double-click on it.  Awesome, you just ran your first PowerShell script!  What do you mean it didn’t run?  It came up in NotePad?

Oh yeah.  By default, for security reasons, double-clicking on a PowerShell script doesn’t run it.  To do that you have a couple of options.  First is to open up PowerShell and run the script from PowerShell's command line.  To do that you simply  type:

C:\MyScripts\MyCoolScript.ps1

If your current folder is already C:\MyScripts you’ll type:

.\MyCoolScript.ps1

Note that we prefaced the script file with “.\”.  Without that, PowerShell thinks it’s a built-in command and yells that it doesn’t recognize it.

OK, you’ve typed it in, hit enter and away it goes, no?  Except that all you see is:

File C:\MyScripts\MyCoolScript.ps1 cannot be loaded because the execution of scripts is disabled on this system. Please see "get-help about_signing" for more details.
At line:1 char:11
+ .\test.ps1 <<<<
    + CategoryInfo          : NotSpecified: (:) [], PSSecurityException
    + FullyQualifiedErrorId : RuntimeException

$%!#$%!^&*#…OK, ok, breath…again…deep breath…Yet another security “feature”.  With this one type at the command line:

Set-ExecutionPolicy RemoteSigned
Or
Set-ExecutionPolicy Unrestricted

You only need to run this once and it will allow you to run scripts.  When setting RemoteSigned, any local scripts will run as-is, but remote scripts will need to be digitally signed.  Like Enable-PSRemoting, you’ll need to open PowerShell as administrator.

But I’m not an administrator!  The execution policy is not a true security setting, it’s simply there to help prevent the inadvertent running of malicious scripts.  You can actually set the execution policy when you open PowerShell from the command line by using the –ExecutionPolicy argument, using the same RemoteSigned or Unrestricted value.  This will only set the execution policy for that session.

Note that when using the Set-ExectuionPolicy you can set the scope of the setting using the –Scope argument to be either the current process (-Scope Process, same as setting it on the command line), current User (-Scope CurrentUser) or the local machine (-Scope LocalMachine).  The default value is LocalMachine.

Run-Executable

OK, so one of the promises of PowerShell is that not only does it do all this cool new stuff, but all your favorite DOS commands are aliases of the new PowerShell commands, but that you can also run your old executables just like you used to….

Well not so fast….

Running a straight executable such as MyExe.exe, works just fine as long as you’re in the exe’s folder or it resides in a folder in the PATH environment variable.

Try passing to start passing it command line arguments and things start to get squirly.

This is due to how PowerShell handles command line arguments.  PowerShell has three types of arguments:

• Positional – these arguments are expect to be in a specific position such as:
  • Run-Command “Param1Value”
• Named – these arguments are proceeded by the parameter name and can be in any position as follows (note that I’m passing a string literal to Param2 and a variable value to Param1:
  • Run-Command –Param2 “Param2Value” –Param1 $Param1Value
• Switch Parameters – These parameters are either bolean parameters that are either present or not such as:
  • Run-Command –SwitchedOn

PowerShell tries to treat executable paramters the same way.  This works great if your executable uses the same format, but if you’re trying to run MsiExec you’ve got a problem.

MsiExec /i MyInstall.msi

Will work fine, but try:

$MyCustomInstallFolder = “D:\Custom Program Files”
MsiExec /I MyInstall.msi TARGETDIR=$MyCustomInstallFolder

Not so much.  the problem is is that what is actually getting passed is:

MsiExec /i MyInstall.msi “TARGETDIR=D:\Custom Program Files”

MsiExec ends up ignoring the TARGETDIR parameter because PowerShell didn’t recognize TARGETDIR as a named parameter and treated it as a positional parameter, surrounding it with quotes because the expanded string contained spaces.

After fighting with this for quite some time (and doing a fair amount of Googling), I ended up writing the following function that utilizes the .NET Process object to execute an executable, passing a string variable for the entire command line.

Function Start-Process
{
    Param([string]$Executable,
    [string]$Arguments,
    [string]$WorkingFolder,
    [int]$Timeout = 240000,
    [switch]$ShowStandardOutput)
   
    Write-Host ("Starting Process, {0}" -F $Executable);
    Write-Host ("Command Line Args:  {0}" -F $Arguments);
    Write-Host ("Working Folder:  " -F $WorkingFolder);
    Write-Host ("Timeout:  {0}" -F $TimeOut);
    Write-Host ("Show Std Out:  {0}" -F $ShowStandardOutput);
   
    $ProcessInfo = New-Object -TypeName System.Diagnostics.ProcessStartInfo;
    $ProcessInfo.FileName = $Executable;
    $ProcessInfo.WorkingDirectory = $WorkingFolder
    $ProcessInfo.UseShellExecute = $false;
    if ($ShowStandardOutput) {
        $ProcessInfo.RedirectStandardOutput = $true;
    }
    else {
        $ProcessInfo.RedirectStandardOutput = $false;
    }
    $ProcessInfo.RedirectStandardError = $false;
    $ProcessInfo.Arguments = $Arguments;
    $ProcessInfo.CreateNoWindow = $false;
    $ProcessInfo.ErrorDialog = $false;
   
    $Process = New-Object -TypeName System.Diagnostics.Process;
    $Process.StartInfo = $ProcessInfo;
    $Process.EnableRaisingEvents = $false;
   
    $Process.Start();
    if ($ShowSTandardOutput) {
        $Output = $Process.StandardOutput.ReadToEnd();
        $Output;
    }
    if (-not $Process.WaitForExit($Timeout)) {
        $Process.Kill;
        $ProcessInfo;
        throw "Start-Process - Process timed out";
    }
   
    if ($Process.ExitCode -ne 0) {
        $ProcessInfo;
        throw "Start-Process - Process failed with exit code - " + $Process.ExitCode
    };
}

Since then I’ve read that you can actually run Cmd.exe, passing the entire command line (executable and arguments) as a string, thus doing something similar to what I’m doing with the Process object.

Control-Flow

PowerShell provides a comprehensive set of flow-control constructs, starting with if/elseif/else as follows:

$Value = 2
If ($Value -eq 1) {
Do-Something
}
ElseIf ($Value -eq 2) {
Do-SomethingElse
}
Else {
Do-SomethingCompletelyDifferent
}

Note that we have a completely different set of comparison and logical operators to remember as follows:

Equals	-eq
Not Equal To	-ne
Greater Than	-gt
Greater Than or Equal To	-ge
Less Than	-lt
Less Than or Equal To	-le
Not	-not or !
And	-and
Or	-or

Additionally, if you're doing string comparison, you can force case-sensitive or case-insensitive (default comparison is case-insensitive) by prefacing the operator with a c or i e.g. -ceq is a case-sensitive equal comparison.

In addition to the if flow control, PowerShell also has:

• Do While - Do {Code Block} While (Condition)
• While - While (Condition) {Code Block}
• Do Until -
• For - For ($Index = 1; $Index -le 3; $Index++) {Code Block}
• ForEach - ForEach ($MyObject In $MyObjectsArrayOrCollection) {Code Block}
• Switch -
  

  Switch ($MyValue)
  {
      Result1 {Code Block}
      Result2 {Code Block}
      Default {Code Block}
  }

A couple of good articles on flow control are:

• PowerShell Tutorial 8: Conditional Logic (if, elseif, else, and switch)
• PowerShell Tutorial 9: Getting Loopy

Use-Variable

I am pretty light on the details of variables, particularly around scope, expansion and built-in variables, but PowerShell does have them.  Variables are always prefaced with “$”.  Declaration and assignment of variables is as simple as:

$Number = 2
Or
$Files = Get-ChildItem

In the first case, we’re assigning the number 2 to the variable $Number.  In the second we’re assigning $Files an array of files in the current folder.  Remember that depending on the provider this may not be files.  In the case of:

SQL:\MYSQLSERVER\DEFAULT\Databases\MyDatabase\Tables

we’d be assigning an array of SMO table objects in the MyDatabase database.

I’m a little shaky on variable expansion.  For example:

$Subfolder = “MySubFolder”
Set-Location C:\MyFolder\$Subfolder

will set your current location to C:\MyFolder\MySubFolder.  If you have space in your path you could type:

Set-Location “C:\My Folder\$Subfolder”

and the value of $Subfolder will replace $Subfolder in the path.  However, I seem to have had cases where the string replacement doesn’t happen and I simply end up with a string “C:\My Folder\$Subfolder”

When in doubt, you can look to string concatenation as follows:

$Subfolder = “MySubFolder”
$Folder = “C:\MyFolder\” + $Subfolder

Or PowerShell’s equivalent of the .NET string.Format(string, arg1, arg2, …) as follows:

Set-Location (“C:\My Folder\{0}” –F $Subfolder)

Although you don't see it often, you can type variables by declaring them with a specific .NET type as follows:

[int]$MyInteger = 1

This will explicitly type the variable as an integer.  There are two special types of variables and literal assignments, arrays and hastables.  You can define and assign a literal array as follows:

$MyArray = @(1, 2, 3)
$MyValue = $MyArray[1]

This creates a 3 integer, zero-indexed array and then assign the second value, 2 to the variable $MyValue.  A hash table variable, or dictionary, creates a list of name/value pairs as follows:

$MyHashTable = @{"Value1" = 123, "Value2" = 456}
$MySecondValue = $MyHashTable["Value2"]

You can add a new value by simply assigning a value to an unused name as follows:

$MyHasTable["Value3"] = 789

Or remove a value using the .Remove method as follows:

$MyHashTable.Remove("Value2")

Don't forget you can do all of this interactively from the command line and viewing the value of the variable is as simple as typing the variable name at the command line and hitting enter.

As noted at the beginning, I’m still a little light on the details of variables.  I believe there are a number of scope rules around access to variables inside modules etc. that I am not familiar with so Google will be your friend with this.

A good article I found on variables is PowerShell Tutorial 7: Accumulate, Recall, and Modify Data.

Process-Pipeline

PowerShell allows you to pipe the results of one command into the next.  It doesn’t simply pass along the text output but sends the entire resulting .NET object.  This may be an array or IEnumerable collection of objects.

For example, Get-ChildItem *.txt will return a list of files in the current folder.  However what it’s actually  returning is a list of System.IO.FileInfo objects.  Typing Get-ChildItem *.txt | Remove-Item will cause it to pass along that list of objects to the Remove-Item cmdlet which will subsequently delete them.

That’s not so interesting because you could have simply typed Remove-Item *.txt (or Del *.txt).  But what if you wanted to delete only text files larger than 10KB?  Try this:

Get-ChildItem *.txt | Where-Object {$_.Length -gt 10000} | Remove-item

So what’s going on here?  First we’re taking the output of the Get-ChildItem *.txt cmdlet which returns an array of System.IO.FileInfo objects representing all of the text files and passing it to the Where-Object.  One of the possible arguments for the Where-Object (aliased as Where) is a script block.

The script block here is {$_.Length > 10000}.  What’s going on here is that the Where-Object cmdlet is passing each input object (i.e. each FileInfo object) into the script block.  The passed in object is represented in the script block as “$_”.  We’re then testing to see whether it’s Length property is greater than 10000 using the –gt greater than operator and returning only those that evaluate to true. (Yes, PowerShell doesn’t use the standard operator symbols we’re used to but that’s another blog entry).

Next along we’re passing along the resulting text files bigger than 10KB to Remove-Item and deleting them.  Note that since we’re dealing with standard .NET FileInfo objects we could have used any of it’s properties such as LastAccessTime or Attributes.

WhatIs-PowerShell -?

PowerShell is Microsoft’s scripting alternative to ye olde DOS command line.  Although it shares many of it’s concepts, it it immensely more flexible and extensible.

It’s primary purpose is to allow system admins to accomplish more through a command line interface and scripts using a more standard command syntax than the collection of DOS commands, VBScripts and random executables that are available with the standard cmd.exe interface.

At it’s base it’s an interactive shell that allows you to type commands and view the results.  Like the DOS command line, you can create script files (.PS1 instead of .BAT).  Unlike the DOS command line you can load extensions in the form of Snap-ins and Modules (Snap-Ins are a version 1 concept that can still be loaded but have largely been replaced by Modules in version 2).

CmdLets & Providers

There are two important concepts in PowerShell, CmdLets and Providers.

CmdLets are commands you type at the command line such as Set-Location and Get-ChildItem.  Note that these can be aliased.  You can type Del *.txt and it will delete all text files in the current folder because Del is an alias of Remove-Item. 
You’ll notice that the non-aliased naming convention for CmdLets is Verb-Object.  Not only that, but if you define a CmdLet or function that doesn’t use one of the pre-defined verbs, PowerShell will yell at you, although it will still function correctly (You can get a list of approved verbs by typing Get-Verb).

Providers on the other hand allow you to navigate systems through a folder system.  The most obvious is the file system.  The File System provider allows you to type CD C:\Users (translates to Set-Location C:\Users) which will set your current location to the C:\Users folder.

However, unlike the DOS command line, we’re no longer limited to the file system.  Load up the SQL Server provider, type CD SQL:\MYSQLSERVER\DEFAULT\Databases\MyDatabase\Tables, type Dir (translates to Get-ChildItem) and you’ll get a list of the tables in the MyDatabase database on the default SQL instance on MYSSQLSERVER.   there are also providers for the registry and IIS, allowing for easy navigation.

Hello-PowerShell

So I’m going to go way off the data track for a few posts.  I’ve been working on a data integration project to better integrate our customer’s and our products.  As a SAAS company, I don’t need to write polished MSI installer for public consumption, but I do have to write an installer that will allow our IT staff to deploy and update thousands of instances used by our customers, and as my boss likes to put it, “works like gravity”.  It needs to have minimal touch points and minimal configuration to reduce the risk points. 
I considered MSIs, batch files, .NET apps, and a combination of the above with various command line utilities.  Ultimately, I decided that it was finally time to learn PowerShell.
After a headache inducing introduction, I’ve become quite comfortable with and somewhat enamored of it, for certain, sysadmin types of tasks, to the point that I’ve written initial versions of PowerShell modules in C# for the application to help simplify the automation/scripting of setting up integration configurations.  Although I didn’t completely get away from MSIs and command line utilities, PowerShell did eliminate the need for some and was able to tie the rest together much more nicely than would be possible with the old batch file.
I am by no means yet an expert, and based on some articles I've scanned I've barely scratched the surface, but over the next few blog entries will share some of the pleasure and pain I’ve experienced in working with it.
A couple of things that will greatly help you to start with.  First is Get-Help.  typing this followed by any cmdlet name will get you a brief description of the cmdlet, it’s syntax, list of arguments and related cmdlets.  Adding the –detailed argument to the Get-Help cmdlet will return detailed information on each of the arguments as well as examples.
If you don’t quite remember the name of the cmdlet, you can type in part of it and Get-Help will return a list of cmdlets containing that string.  e.g. searching on “Session” will return all of the session cmdlets.  Helpful when you forget that Get-PSSession has a “PS” in it.
Of course the next thing that will help is Google, but if you want to skip that there’s a couple sites that Google has taken me to several times:

• PowerShell Pro (http://www.powershellpro.com/)
• PowerShell ABC's (http://devcentral.f5.com/weblogs/Joe/Tags/PowerShell%20ABCs/default.aspx) - 26 very useful articles by Joe Pruit.
• PowerShell.com (http://powershell.com/cs/)
• PowerShell Intro on MSDN (http://msdn.microsoft.com/en-us/library/aa973757(v=vs.85).aspx)
• Windows PowerShell Blog (http://blogs.msdn.com/b/powershell/)