Search results for 'app:weblogs' matching tag 'scripting techniques'

I Found This Module—What Do I Do?

Anonymous — Wed, 15 May 2013 05:00:00 GMT

Summary: Microsoft Scripting Guy, Ed Wilson, talks about how to use a Windows PowerShell module.

Hey, Scripting Guy! I found this module in the Scripting Guys Script Repository. Now what do I do?

—SH

Hello SH,

Microsoft Scripting Guy, Ed Wilson, is here. This morning I have been busy booking travel to Madrid, Spain for TechEd 2013. I will have a booth there with the Scripting Wife. In addition, I will be joining the Windows PowerShell team for their instructor led lab—it will be way cool. Air travel these days is so much fun, I genuinely look forward to each upcoming flight. This includes my flight to TechEd 2013 in New Orleans, where you can also find the Scripting Wife and me. (I am also conducting a Windows PowerShell instructor led lab in the big easy.)

Note This is the fourth part of a multipart series about using Windows PowerShell functions and modules. Prior to reading this blog, you should read the previous posts:

What do I do with a module I find?

Let us suppose that I find a module such as the Windows Update PowerShell Module in the Scripting Guys Script Repository. What do I do with it? Well, the first thing I need to do is to download and to install the module. But this is where things are actually a bit confusing. This is because I can put the module anywhere I want to put it. One of the great things about Windows PowerShell modules is that no installer is required. Most modules, in fact, use a simple copy and paste type of installation (the so-called XCOPY deployment, but you do not need to use XCOPY if you do not wish to do so).

Where do I put the module?

There are two places I can put modules so that Windows PowerShell will automatically recognize them, and will automatically import them. These locations are stored in the PSModulePath environmental variable. From a basic categorization standpoint, one is in my profile/home directory, and the other one is in System32. This output on my computer is shown here.

PS C:\> $env:PSModulePath -split ";"

C:\Users\ed.IAMMRED\Documents\WindowsPowerShell\Modules

C:\Windows\system32\WindowsPowerShell\v1.0\Modules\

It requires admin rights to copy something into the System32 folder, and that is where people sometimes place modules that require admin rights. The problem with this location is that when Windows undergoes servicing, it remotes items from the system folders that it does not know about. This means that your admin type of modules can easily become deleted the next time you run Windows update or apply a service pack.

The problem with storing all modules in my profile/home directory location occurs if I am running as a normal user, and then I need to elevate to an account with admin rights so I can run a module that requires admin rights. My profile/home directory is now a NEW location because I am running as a different user. This makes it painful to navigate back to the old user profile location to launch the module manually.

The answer is simple. Modify the $env:PSModulePath location to include an additional folder—either one on a network, or a folder in an easily accessible location. For example, I have a central data folder that I use to simplify backups (an XCOPY backup, so to speak). I could easily create a central modules folder that is accessible for all users on the computer. This technique is shown here.

PS C:\> $env:PSModulePath = $env:PSModulePath + ';c:\data\modules'

PS C:\> $env:PSModulePath -split ";"

C:\Users\ed.IAMMRED\Documents\WindowsPowerShell\Modules

C:\Windows\system32\WindowsPowerShell\v1.0\Modules\

c:\data\modules

How do I put the module in its location?

Let’s go back to the Windows Update PowerShell Module from the Scripting Guys Script Repository. It is contained in a file called PSWindowsUpdate.zip. I click the PSWindowsUpdate.zip file in the Script Repository, and after I agree to the terms of use, Internet Explorer asks if I want to Open, Save, or Cancel my action. This is shown in the image that follows.

If I select Open, the zipped file opens revealing a subfolder as shown here:

Cool, it seems that all I need to do is to open my module directory and drag the folder from the zipped folder to my module home directory. The problem if I do this is the files in the folder will all be blocked. This is shown in the following image.

I can use Windows PowerShell 3.0 to unblock the files, but it is easier to unblock the files before installation. To do this, save the .zip file, then right-click it to unblock the file prior to extraction. In this way, all the files contained therein are unblocked. However, if I forget to do this, I can use a command such as the following to unblock the files:

PS C:\Users\ed.IAMMRED\Documents\WindowsPowerShell\Modules> gci .\PSWindowsUpdate -Re

curse | Unblock-File

After I copy the unzipped and unblocked Windows PowerShell module files to the module directory, I can import the module and use the cmdlets. Because I am dealing with Windows update, the Windows PowerShell console needs to be elevated. The following error appears if the Windows PowerShell console is not elevated.

After I elevate Windows PowerShell, I use the Import-Module cmdlet to import the module, and I use the Get-Command cmdlet to see what commands are exposed by the module. This is shown here.

Now that I see the commands, I can use them just like any other Windows PowerShell command from any other module. So I can check to see what updates are available via the Get-WUList cmdlet (function) as shown here:

PS C:\> Get-WUList

ComputerName Status KB Size Title

------------ ------ -- ---- -----

EDLT ---H-- KB2694771 5 MB Bing Desktop v1.2

To install an update, I use the Get-WUInstall function, and to hide an update I use the Hide-WUUpdate command. Pipeline support is available.

I can even check to see if a reboot is required as shown here:

PS C:\> Get-WURebootStatus

Reboot is not Required.

SH, that is all there is to using a Windows PowerShell module. Join me tomorrow when I will reveal the 2013 Scripting Games Event 4.

I invite you to follow me on Twitter and Facebook. If you have any questions, send email to me at scripter@microsoft.com, or post your questions on the Official Scripting Guys Forum. See you tomorrow. Until then, peace.

Ed Wilson, Microsoft Scripting Guy

I Found this PowerShell Function—Now What Do I Do? Part 3

Anonymous — Tue, 14 May 2013 05:00:00 GMT

Summary: Microsoft Scripting Guy, Ed Wilson, talks about combining functions into a single function file, and using them in scripts.

Microsoft Scripting Guy, Ed Wilson, is here. This morning is sort of mellow. It seems as if the clouds are touching the ground, and all sound is suppressed by a thick cloth batten. After seemingly weeks of rain, it is nice to have a not so wet day. I am on the lanai sitting in our porch swing reading my email via Outlook Web Access on my Surface RT. I love the long battery life and the portability of this device, and the fact that it has Windows PowerShell makes it even better.

Note This is the third part of a multipart series about using Windows PowerShell functions and modules. Prior to reading this blog, you should read the previous posts:

If one function is cool, then two are even better

Yesterday in Part 2, I talked about dot sourcing a script that contains a function into the Windows PowerShell console so I could use the function just like it was a cmdlet. Today I want to expand on that idea just a bit by including two functions in a script file. The two functions use WMI to create a similar output to standard CIM functions in Windows 8. The equilivant functions in Windows 8 are Get-Volume and Get-NetAdapter. Here is the content of the two WMI functions:

TwoWmiFunctions.ps1

Function Get-Volume

{

Param($cn = $env:computername)

Get-WmiObject -class win32_volume -ComputerName $cn|

Select-Object driveletter, @{LABEL='FileSystemLabel';EXPRESSION={$_.label}},

filesystem,

@{LABEL="Size";EXPRESSION={"{0:N2} Gigabytes" -f ($_.capacity/1GB) }},

@{LABEL="SizeRemaining";EXPRESSION={"{0:N2} Gigabytes" -f ($_.freespace/1GB) }}

} #end function Get-Volume

Function Get-NetAdapter

{

Param($cn = $env:computername)

Get-WmiObject win32_networkadapter |

Where-Object {$_.netconnectionstatus} |

Select-Object name,

@{LABEL='InterfaceDescription';EXPRESSION={$_.Description}},

@{LABEL='ifIndex';EXPRESSION={$_.Index}},

@{LABEL='Status';EXPRESSION={

If($_.netconnectionstatus -eq 2){"not present"}

If($_.netconnectionstatus -eq 4){"up"}}}

} # end function get-NetAdapter

For ease of use, I have uploaded these functions to the Scripting Guys Script Repository: Two WMI Functions.

Using the function script by dot sourcing it

To dot source the script that contains the two functions, all I need to do is to place a period (dot) at the beginning of the console line, and then use the path to the script that contains the functions. I can then use the functions directly. This is shown here.

. C:\fso\TwoWmiFunctions.ps1

The following image shows dot sourcing the script that contains the two functions and then using the two functions.

Dot source to interop between Windows versions

Lots of people are migrating to Windows 8 on their desktops; but unfortunately for many network administrators, they are forced to interop between Windows 8 and other versions of Windows. One of the things that is great about Windows 8 (and Windows Server 2012 for that matter) are the many CIM functions that wrap WMI classes. These are convenient and easy to use. However, for down-level systems, I still need to use the WMI classes. To avoid really cluttering up a script with a bunch of WMI code, I can use dot sourcing to handle the transition period. Here is an example of how that might work:

if(gcm get-volume){Get-Volume} ELSE {. C:\fso\TwoWmiFunctions.ps1; Get-Volume}

So all I need to do is to use Get-Command to see if the Get-Volume function (available in Windows 8) exists. If it does, I call the Get-Volume command. If the Get-Volume function is not available (because the version of Windows is older than Windows 8), I dot source my TwoWMIFunctions.ps1 script that contains my two functions, and then I call Get-Volume from the dot-sourced script. This makes for a nice transitional bit of code.

Note When you create this sort of transitional function, ensure that the property names are the same. In this way, using one function or the other will also be the same. In my example TwoWmiFunctions.ps1 script, I had to rename several WMI class property names for compatibility.

In the following image, I use the dot-source technique to bring in the script that contains the compatibility functions.

Now What Do I Do? Week will continue tomorrow when I will talk about using a Windows PowerShell module. It is really cool, and you do not want to miss it.

Ed Wilson, Microsoft Scripting Guy

I Found this PowerShell Function—Now What Do I Do? Part 2

Anonymous — Mon, 13 May 2013 05:00:00 GMT

Summary: Microsoft Scripting Guy, Ed Wilson, continues his discussion about what to do with a Windows PowerShell function.

Microsoft Scripting Guy, Ed Wilson, is here. Last week I did not get a chance to finish answering a question from JB about how to use a Windows PowerShell function.

Note This is the second part of a multipart series about using Windows PowerShell functions and modules. You should read the first blog post, I Found this PowerShell Function—Now What Do I Do? – Part 1 prior to reading this post.

Functions promote code reuse

In the first installment in this series about using functions, I talked about the more traditional technique of copying and pasting the function directly into a script. This works well if you want to write a script. But one of the powerful things about Windows PowerShell is that I do not have to write a script. In fact, the great thing about Andy Schneider’s Set-ScreenResolution function is that he wrote it as a function.

Top ten Windows PowerShell function best practices

Of course, being able to reuse the code depends on a well written function. Here is my top ten list of Windows PowerShell function best practices.

A function should:

Use the standard Verb-Noun naming convention.
Do one thing and do it well.
Return an object.
Incorporate comment-based Help.
Expose parameters instead of using hard-coded values.
Accept piped input if it makes sense for the use-case scenario.
Run and return default information if it makes sense for the use-case scenario (instead of requiring input, or returning an error when it is run without parameters).
Offer parameter aliases for common parameters (for example, CN for ComputerName).
Name parameters in accordance with standard Windows PowerShell cmdlets (for example ComputerName instead of server, laptop, or machine).
Use parameter validation techniques to limit user input.

Note For more information about Windows PowerShell functions, see this collection of Hey, Scripting Guy! Blog posts.

Save the function into a .ps1 script file

So suppose you find a well-written function and you want to be able to use it in the Windows PowerShell console. A well-written Windows PowerShell function will, in fact, act and behave like a Windows PowerShell cmdlet. So bringing it into the Windows PowerShell console will enhance the interactive use experience of Windows PowerShell.

Let’s go back to the Set-ScreenResolution function that I used last week (written by Andy Schneider). I go to the Scripting Guys Script Repository, find the Set-ScreenResolution script and copy it to the clipboard. Now, I paste it into the Windows PowerShell ISE, and I save it with a file name like Set-ScreenResolutionFunction.ps1. Here is the script:

Dot source the script file

When I have the function stored in a script file, I can use the function in my Windows PowerShell console, or even in another Windows PowerShell script. The key to doing this is to store the script file that contains the function in an easily locatable folder. For me, that folder is off the root of drive C (C:\fso). I have used this folder for my scratch folder for over a decade.

Keys to success for using dot sourcing

Save the function into a script file with a similar name to the function.
Save the script file that contains the function in an easily accessed location.
Make sure that the script file contains only the function, and no “entry code” that will automatically launch the function.
Dot source functions into scripts that may have code that changes for ease of update.
Use the syntax: period, space, path to script (<.><space><path>).

To dot source the Set-ScreenResolutionFunction.ps1 script into the Windows PowerShell console, I use the syntax shown here:

. C:\fso\Set-ScreenResolutionFunction.ps1

To call the Set-ScreenResolution function, I type the function name, just like I would do with a regular Windows PowerShell cmdlet. In fact, tab expansion even works. This is shown here:

Set-ScreenResolution -Width 800 -Height 600

This technique is shown in the image that follows.

I can also use this technique in the Windows PowerShell ISE. In the image that follows, I dot source the Set-ScreenResolutionFunction.ps1 script into my script.

Well, that is about all for now. Now What Do I Do? Week will continue tomorrow when I will continue to talk about using Windows PowerShell functions.

Ed Wilson, Microsoft Scripting Guy

Weekend Scripter: Playing with PowerShell's Get-Variable Cmdlet

Anonymous — Sat, 11 May 2013 05:00:00 GMT

Summary: Microsoft Scripting Guy, Ed Wilson, spends some time playing around with the Get-Variable cmdlet.

Microsoft Scripting Guy, Ed Wilson, is here. This morning I am doing something a little different. Instead of drinking English Breakfast tea, I woke up feeling like I wanted Oolong tea instead. So I made a pot of Oolong tea with a spoonful of jasmine buds, a half spoon of peppermint leaves, three juniper berries, and half of a crushed cinnamon stick. It is quite invigorating, without being too overbearing.

Checking the value of a variable

So I am sitting on the lanai in my porch swing, and I just finished checking the email for the scripter@microsoft.com email alias. I received an email asking why I would bother using the Get-Variable cmdlet, when I can simply reference the variable to see the value? The reason is that there are many more things I need to do with variables than simply see the value contained inside the variable. The following example assigns a directory listing to the $dir variable:

$dir = dir -Directory | ? lastwritetime -gt $([datetime]'4/1/13')

To see the value that is contained in the $dir variable, I can type $dir. The command and the output are shown in the image that follows.

Use Get-Variable

I can also do this by using the Get-Variable cmdlet. When use Get-Variable, both the name and the value appear. To return only the value, I group the expression, and get the Value property as shown here:

(Get-Variable dir).value

This command and the associated output are shown in the image that follows.

Use the Variable provider

But there are other ways to retrieve values from Windows PowerShell variables. For example, I can use the Variable provider and access the value from the Windows PowerShell Variable drive. I do this by using the command shown here:

$variable:dir

The command and the output are shown in the following image.

Because the Variable provider creates a PSDrive named Variable, I can use the standard Windows PowerShell cmdlets to work with the variable. For example, I can use Get-Item as shown in this example:

Get-Item -Path Variable:\dir

But if I only want the value of the Dir variable, I need to select the Value property:

(Get-Item -Path Variable:\dir).value

The commands and associated output are shown in the image that follows.

One of the cooler things to do is to use the Get-Content cmdlet to obtain the contents of the variable. When using this technique, only the first value from the array returns. This is shown here:

PS C:\> Get-Content variable:\dir

Directory: C:\

Mode LastWriteTime Length Name

---- ------------- ------ ----

d---- 4/23/2013 12:41 PM fso

Examining the type of a variable

I am sure you know that there are different types of variables in Windows PowerShell. If I use the Get-Variable cmdlet, pipe the results to the Format-List cmdlet, and choose all of the properties, I obtain some pretty interesting information. This is shown here:

PS C:\> Get-Variable dir | fl *

PSPath : Microsoft.PowerShell.Core\Variable::dir

PSDrive : Variable

PSProvider : Microsoft.PowerShell.Core\Variable

PSIsContainer : False

Name : dir

Description :

Value : {fso, fsox, Program Files, Program Files (x86)...}

Visibility : Public

Module :

ModuleName :

Options : None

Attributes : {}

If I take the $dir variable and pipe it to the Get-Member cmdlet, it returns information about the objects that are contained in the variable, and not about the variable itself.

$dir | get-member

The command and output from the command are shown in the image that follows.

To find information about the variable itself, I use Get-Variable to return the variable, and then I pipe the result to the Get-Member cmdlet:

Get-Variable dir | Get-Member

The command and output from the command are shown here.

Finding different types of variables

Unfortunately, this does not return anything about the type of Windows PowerShell variable. So what is the easy way to find the variable type? Use the Get-Variable cmdlet and pipe the returned objects to the Get-Member cmdlet. Next, I select only the TypeName property, and I use the Unique switch to ensure only unique instances return. Here is the command and the results:

PS C:\> Get-Variable | Get-Member | select typename -Unique

TypeName

--------

System.Management.Automation.PSVariable

System.Management.Automation.QuestionMarkVariable

System.Management.Automation.LocalVariable

System.Management.Automation.SessionStateCapacityVariable

System.Management.Automation.NullVariable

When I know the different types of variables, I can use Windows PowerShell to list a particular type of variable. To do this, I pipe the results of Get-Variable to the Where-Object. In my Where-Object filter, I use the PSObject property so I can reference the underlying type. This technique is shown here where I find all variables of the type LocalVariable.

Get-Variable | where {$_.psobject.typenames -match 'local'}

The command and output from the command are shown here.

Join me tomorrow for the exciting conclusion to the Windows PowerShell and Security series by Yuri Diogenes and Tom Schinder. To catch up, read the two previous posts in this series.

Ed Wilson, Microsoft Scripting Guy

Weekend Scripter: Improve Performance When Combining PowerShell Arrays

Anonymous — Sat, 27 Apr 2013 05:00:00 GMT

Summary: Microsoft premier field engineer, Chris Wu, talks about combining Windows PowerShell arrays.

Microsoft Scripting Guy, Ed Wilson, is here. Chris Wu, a Microsoft PFE, is back to share his knowledge. See previous Hey, Scripting Guy! Blog guest posts from Chris.

Here is contact information for Chris:

Twitter: https://twitter.com/chwu_ms
Facebook: https://www.facebook.com/mschwu
LinkedIn: http://ca.linkedin.com/in/mschwu

Take it away Chris…

While teaching a Windows PowerShell workshop, I was asked about how to combine two arrays of different objects (which share one key property) into one that contains objects with properties from both source objects. One real world scenario is to merge information retrieved from Active Directory (a list of Active Directory users and their properties) and Exchange Server (mailboxes).

The current approach by the student is to use two-level loops, which has seen performance issues when source arrays become huge in size (the following code snippet uses dummy data for demonstration purposes).

$ADList = @"

chwu,chwu@microsoft.com,Chris Wu

tst1,,Test User1

tst2,tst2@contoso.com,Test User2

"@ | ConvertFrom-Csv -Header Name,mail,CN

$EXList = @"

chwu,ex1.contoso.com

tst2,ex2.contoso.com

"@ | ConvertFrom-Csv -Header Name,MailServer

$Result = @()

foreach($ad in $ADList) {

$Match = $false

foreach($ex in $EXList) {

if ($ad.Name -eq $ex.Name) {

$Result += New-Object PSObject -Property @{Name=$ad.Name; mail=$ad.mail; CN=$ad.CN; MailServer=$ex.MailServer}

$Match = $true

}

if(-not $Match) {

$Result += New-Object PSObject -Property @{Name=$ad.Name; mail=$ad.mail; CN=$ad.CN}

}

In this post, I will explore several options to improve the performance and cleanness of this code snippet.

The first thing we can do is remove the use of the $Result array, which has two drawbacks:

Every assignment operation will create a new array in memory with data copied from the source, which is inefficient.
It defeats the streaming benefit of the WindowsPowerShell pipeline because it returns all objects as a whole at the end of the processing. A best practice in Windows PowerShell is to emit an individual object whenever it’s ready.

Another performance issue stems from the use of an inner loop to search for a matching record in the second array, which basically multiplies the total number of iterations. We can utilize a hash table for faster lookup. The Group-Object cmdlet offers a convenient AsHashTable parameter that can be used here.

Please be warned that the value portion of each entry is an array of matching records. If we are grouping records by using a property with unique values (such as SamAccountName), those arrays will apparently contains one single element each.

So an enhanced version of the code snippet is like this (with the constructing source arrays removed):

$h = $EXList | Group-Object -Property Name -AsHashTable

$ADList | %{

if($h[$_.Name]) {

New-Object PSObject -Property @{Name=$_.Name; mail=$_.mail; CN=$_.CN; MailServer=$h[$_.Name][0].MailServer}

} else {

New-Object PSObject -Property @{Name=$_.Name; mail=$_.mail; CN=$_.CN}

}

The last (but not the least) idea is to sort both arrays based on the key property (user name) beforehand, then we can pair records in a single iteration. Note that in this particular example, users found in Active Directory is a superset of users in Exchange, so we need a pointer variable to deal with this little quirk.

$ADList = @"

chwu,chwu@microsoft.com,Chris Wu

tst1,,Test User1

tst2,tst2@contoso.com,Test User2

"@ | ConvertFrom-Csv -Header Name,mail,CN | Sort-Object -Property Name

$EXList = @"

chwu,ex1.contoso.com

tst2,ex2.contoso.com

"@ | ConvertFrom-Csv -Header Name,MailServer | Sort-Object -Property Name

$ADList | % {$p = 0} {

if($_.Name -eq $EXList[$p].Name) {

New-Object PSObject -Property @{Name=$_.Name; mail=$_.mail; CN=$_.CN; MailServer=$EXList[$p].MailServer}

$p++

} else {

New-Object PSObject -Property @{Name=$_.Name; mail=$_.mail; CN=$_.CN}

}

The last two snippets perform much better than the original one, but which one is faster remains a question (I haven’t tested them against large arrays just yet). I would like to hear about your results, and I welcome your thoughts and ideas.

~Chris

Thanks Chris excellent blog post. Join me tomorrow for more cool Windows PowerShell stuff.

Ed Wilson, Microsoft Scripting Guy

Weekend Scripter: Pick Comments from a PowerShell Script

Anonymous — Sat, 13 Apr 2013 05:00:00 GMT

Summary: Guest blogger, Bob Stevens, shares a script to pick out comments from a Windows PowerShell script.

Microsoft Scripting Guy, Ed Wilson, is here. Today we have a new guest blogger, Bob Stevens. I made Bob’s virtual acquaintance recently when I did a Live Meeting presentation to the Twin Cities PowerShell User Group.

Here is Bob’s contact information:

Blog: Help! I’m Stuck in My Powershell!
Twitter: @B_stevens6
LinkedIn: Robert Stevens

The floor is yours, Bob…

As a local Help Desk technician, I run into many repetitive support tasks. From low toners to Internet Explorer issues, I have done it all. About three months ago I discovered that I could use PowerShell to automate a number of these tasks, thereby freeing my time for some of the more unusual issues. Fortunately, all of the computers at my site have Windows PowerShell 2.0 installed, so it was a matter of ensuring that they can run scripts. This can be done by changing the Set-ExecutionPolicy cmdlet to Unrestricted in the following manner:

Set-ExecutionPolicy Unrestricted

When the work is done, switch it back to the organization default with:

Set-ExecutionPolicy Remote-Signed

Set-ExecutionPolicy governs which scripts can be run on any given system. By setting it as Unrestricted, I am removing all restrictions. I switch it back to Remote-Signed to prevent users from running scripts that can potentially damage a system, thereby presenting a potential for data loss.

Fast forward three months and multiple scripts later…

It dawned on me that I would need to create documentation for each of these scripts. Documentation provides my coworkers with the insight they need to understand the purpose and functionality of my work and to pick up where I left off should the script need to be altered. Thankfully, like a good Windows PowerShell scripter, I commented liberally throughout my scripts to ensure that I knew where I would need to alter it in the future. To this end I started working on a script to pull comments. I knew that I habitually use single line comments for documentation and block comments for commenting out blocks of code. Happy accident because the script I devised only pulls the first and the last lines of a block comment.

Note For simplicity, I name all directories a variation of “foo” and all input files a variation of “foo.*”. You can set foo as whatever you want.

As usual I started with setting my location:

Set-Location “C:\foo”

Next we set our source script file as a variable. I use variables in my scripts to enable me to change one line of code, rather than five lines, thereby reducing the chance of an error. Variables are defined by the dollar sign ($).

$script = “foo.ps1”

We need to define an output variable as $out. Note that I used the $script variable in the variable value. This will result in the file name of foo.ps1 comments.txt. This is to differentiate between output files. For this to work, there must be a space between $script and comments.txt:

$out = “$script comments.txt”

Now that we have defined the output file name, we need to create the output file itself, and I do this with the New-Item cmdlet. Of course, we need to define the object as a file—otherwise we get a dialog box asking us if it’s a file or folder:

New-Item “out” -ItemType File

Now our preparation is complete:

Set-Location "c:\foo"

$script = "foo.ps1"

$out = "$script comments.txt"

New-Item "$out" -ItemType File

We need to pull the content of our source file with the Get-Content cmdlet:

Get-Content $script

The next line is to prevent Windows PowerShell from appending the output to output that already exists in the variable by creating an array, this is done with the array (@) operator, followed by both parentheses:

$comments = @()

This is where the magic takes place. We need to use the Select-String cmdlet. This command requires two parameters: Pattern and File. Both values need to be quoted if you are not using a variable to define it. As we are searching for comments, we are going to select strings that contain “#”:

Select-String -Pattern “#” $script

This is a bit more complex, and it requires stringing three commands together, so we use the pipe (|) operator. The pipe operator merely states do “this” and then do “that” with the output of “this.” Pipe operators must always have a space preceding and succeeding it:

Select-String -Pattern “#” $script |

For our purposes, we are going to say, “For each object, do this.” Coincidentally (or not), Microsoft decided to add a Foreach-Object cmdlet for just this purpose! And everything that you are doing with Foreach-Object must be in braces to group them together:

Select-String - Pattern “#” $script |

Foreach-Object {}

When we string commands like this together, formatting is important—not for functionality, but for readability. Now we need to comment the full line where “#” appears. It is important to note that you must use “+=”, or you will end up with an empty file:

Select-String - Pattern “#” $script |

Foreach-Object {

$comments += $_.line

}

We need to tell Windows PowerShell to grab everything after “#” in that string. This is tricky, but it can be done with the context.postcontext definition:

Select-String - Pattern “#” $script |

Foreach-Object {

$comments += $_.line

$comments += $_.context.postcontext

}

We now need to tell Windows PowerShell to extract everything that we just defined within the Foreach-Object curly brackets:

Select-String - Pattern “#” $script |

Foreach-Object {

$comments += $_.line

$comments += $_.context.postcontext

}

$comments

Finally, we dump our output into the output file $out with the Set-Content cmdlet:

Select-String - Pattern “#” $script |

Foreach-Object {

$comments += $_.line

$comments += $_.context.postcontext

}

$comments | Set-Content $out

The complete script looks something like this:

Set-Location "c:\foo"

$script = "foo.ps1"

$out = "$script comments.txt"

New-Item "$out" -ItemType File

Get-Content $script

$comments = @()

Select-String -Pattern "#" $script |

Foreach-Object {

$comments += $_.line

$comments += $_.context.postcontext

}

$comments | Set-Content $out

The result should take the following input:

And give you the following output (Select-String -pattern “#” shows up because it contains a “#”):

This saved me an hour now and countless future hours that I would spend extracting comments for documentation.

When I was verifying my work, I ran across the following note to myself stating that I referenced a Rob Campbell in another script. Some of the code made it in here.

Rob Campbell, Mjolinor: How do you extract data from a txt file with powershell. As always, input is always appreciated.

Thank you for your time. I uploaded the complete script to the Script Center Repository: Extracting Comments from a Script with PowerShell.

~Bob

Thank you, Bob, for sharing your script and your insight with us today. Join us tomorrow when Bob talks about a script he wrote to clean up user profiles. It is cool, and you do not want to miss it.

Ed Wilson, Microsoft Scripting Guy

Named Arguments for PowerShell Functions: Best Practices

Anonymous — Thu, 11 Apr 2013 05:00:00 GMT

Summary: Microsoft Scripting Guy, Ed Wilson, talks about using named arguments in Windows PowerShell functions.

Microsoft Scripting Guy, Ed Wilson, is here. If I go to the trouble of writing a Windows PowerShell script, I generally do not use unnamed arguments (such as $args as I illustrated yesterday in Accepting Arguments for PowerShell Functions: Best Practices). Instead I create named arguments for my functions. It is just so much more powerful, and so much more flexible. Besides, I can still pass values appositionally in an unnamed fashion if I wish to do so.

Create a named argument in five easy steps

In yesterday's blog, I said that there are only three requirements to create a function in Windows PowerShell:

The Function keyword
The name of the function
A script block

To create a named argument in a Windows PowerShell function, I need only two additional things:

The Param keyword
A variable to hold the argument inside a pair of parentheses

The following script illustrates this technique:

Function myfunction

{

Param($myargument)

"This value of `$myargument is $myargument"

}

To use MyFunction, I first have to run the script. This loads the function into memory and makes it available via the function PSDrive. Because I have not saved the script containing the function, when I run the script, it appears in the Console pane below the Script pane. When the script runs, the Windows PowerShell prompt returns, and I can call the function by typing the name of the function. I then supply a value for the argument by typing it. This is shown in the image that follows.

Keep in mind that tab expansion works here. So I do not have to type the entire name of MyFunction, nor do I need to type the complete name of MyArgument. In fact, I only had to type my and press the Tab key to get the MyFunction command onto the command line. When I type the hyphen (–) for the named argument (parameter) a pop-up list appears, as shown in the following image.

The advantage of using named arguments (parameters) is that I do not need to name the parameter if I do not want to. I can use it as a positional parameter. In this manner, it behaves like an unnamed argument ($args). This is shown here.

PS C:\> myfunction "this is a string"

This value of $myargument is this is a string

Because creating named parameters in Windows PowerShell is so easy, and because using the Param keyword is the entry into the world of advanced functions, I never use $args in a Windows PowerShell script. Because it is an automatic variable that becomes available in certain circumstances, using $args is more difficult to understand because nothing has been created in the script. It is just there.

On the other hand, because the Param block is declared and available for inspection, it makes sense, and is easier to understand. If I begin with a script that uses $args and I later decide that I need to add functionality, I will have to add a Param block to get access to advanced features.

Join me tomorrow when I will welcome guest bloggers Yuri Diogenes and Tom Shinder back with the second installment in their security series. If you want to refresh your memory, check out their first installment in the series:

Security Series: Using PowerShell to Protect Your Private Cloud Infrastructure

Ed Wilson, Microsoft Scripting Guy

Accepting Arguments for PowerShell Functions: Best Practices

Anonymous — Wed, 10 Apr 2013 05:00:00 GMT

Summary: Microsoft Scripting Guy, Ed Wilson, talks about the best practices surrounding accepting input for a Windows PowerShell function.

Microsoft Scripting Guy, Ed Wilson, is here. April in the Carolina’s is a special time. In fact, it is my favorite time of the year here. This is because the weather is invariably mild. This week, it has been sunny, moderate temperature, mild humidity, and clear skies. The Scripting Neighbors tell me it is perfect golf weather. It is also perfect “sit on the lanai and write Windows PowerShell scripts” weather. Although I have never had much luck with putting a small ball into an even smaller hole with equipment not designed for that purpose, I can compute the trajectory, and force necessary to accomplish the task with a one-line Windows PowerShell command.

Passing a value to a Windows PowerShell function

If I have a function that I need to pass a value to, I can use the automatic variable $args. This makes the function easy to write and easy to use. The following function uses three steps to create the function. It calls the function keyword, provides a name, and creates a script block that contains code.

function myfunction

{

"the computer name is $args"

}

In the Windows PowerShell ISE, I run the script (I do not have to save the code into a .ps1 file), and the function loads into memory. I can then call the function directly in the execution pane (the dark blue box that follows) and pass a value to the function when I call it. The command line is shown here:

myfunction $env:COMPUTERNAME

The image that follows illustrates creating the function, using $args in the script block, and calling the function from the execution pane.

Anything I add following the name of the function populates the $args variable. In the command that follows, I pass the value mred to the function. Interestingly, I do not have to supply quotation marks when passing the value.

PS C:\> myfunction mred

the computer name is mred

PS C:\> myfunction "mred"

the computer name is mred

I can also use the output from the Get-WmiObject cmdlet for input. Therefore, the following code uses WMI to return the computer name and to pass it to the MyFunction function.

PS C:\> myfunction (gwmi win32_computersystem).name

the computer name is EDLT

One thing to keep in mind, is that when I use the $args automatic variable as illustrated in the MyFunction function, I cannot pipe input to the function. This can actually be a bit of a problem, because it could be really hard to troubleshoot due to the fact that no error arises. This is shown here.

PS C:\> $env:COMPUTERNAME | myfunction

the computer name is

If I want to pipel input to my function, I use the $input automatic variable. The only change that is required to my function is to change $args to $input, as shown here.

function afunction

{

"the computer name is $input"

}

I then pipe the input to the function by using the command shown here.

PS C:\> $env:COMPUTERNAME | afunction

If I attempt to provide positional input to the function instead of piping the input, no error arises, but no value passes either.

The command and associated output are shown in the image here.

Best Practices Week will continue tomorrow when I will talk some more about Windows PowerShell functions.

Ed Wilson, Microsoft Scripting Guy

Using PowerShell Functions: Best Practices

Anonymous — Tue, 09 Apr 2013 05:00:00 GMT

Summary: Microsoft Scripting Guy, Ed Wilson, talks about some best practices for using Windows PowerShell functions.

Microsoft Scripting Guy, Ed Wilson, is here. Windows PowerShell functions are really powerful, and at the same time, they are incredibly simple to create. This makes Windows PowerShell functions flexible and functional. But this flexibility also means that there is a lot of misunderstanding.

A simple function

At the low end (in terms of readability, functionality, features, and so on), a Windows PowerShell function is creatable on a single line interactively at the Windows PowerShell console. The minimum number of elements required to create a function are:

The Function keyword
The name of the function
A script block

That is it. This means that the following is a legitimate function:

function a {}

It does not do anything, but it is legitimate. Running the code at a command prompt in the Windows PowerShell console creates the function. I can then pipe output to it, and even verify that it exists on the Windows PowerShell function PS drive. The following script illustrates these concepts.

PS C:\> function a {}

PS C:\> gps | a

PS C:\> dir function:a

CommandType Name ModuleName

----------- ---- ----------

Function a

Adding functionality to the function

I often need to get a view of data, or a snapshot of data, before I return all of the data. Typically, I pipe the data to the Select-Object cmdlet and pick the last three entries in the data. The following script illustrates this technique (gps is an alias for the Get-Process cmdlet, and select is an alias for the Select-Object cmdlet).

PS C:\> gps | select -Last 3

Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName

------- ------ ----- ----- ----- ------ -- -----------

207 9 1340 3064 40 1848 WUDFHost

405 19 3636 10012 95 1904 WUDFHost

214 18 3336 7852 89 2880 ZeroConfigService

I use this type of code when I am troubleshooting or simply perusing the status of a computer. Because I have established a pattern that pipes data to the Select-Object cmdlet and chooses the last three items, I can put this into a function that accepts pipelined input and outputs the last three items.

Because I am writing the function interactively in the Windows PowerShell console, and because I will be using it a lot, I give it a really short name. Here I call it “l” (as in lower case letter “L”). Inside the script block, I use the automatic variable $input, which is the input piped into a function.

The $input variable only exists inside the context of a function, and only for the time the function is called. If I check the value of $input outside of the function, it is empty. So what I pass to the function is then piped to the Select-Object cmdlet, and the last three items are returned from the function. The function is shown here.

function l {$input | select -Last 3}

To use the function, I pipe results to the function. The following script selects the last three processes.

PS C:\> gps | l

Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName

------- ------ ----- ----- ----- ------ -- -----------

207 9 1340 3064 40 1848 WUDFHost

405 19 3636 10012 95 1904 WUDFHost

214 18 3336 7852 89 2880 ZeroConfigService

I can select the last three services (gsv is an alias) as shown here.

gsv | l

Or maybe I want to look at the last three entries in the event log as shown here.

Get-EventLog application | l

I can even use the range operator and select the last three numbers. This command is shown here.

1..10 | l

These commands and their associated output are shown in the following image.

Best Practices Week will continue tomorrow when I will continue talking about functions.

Ed Wilson, Microsoft Scripting Guy

Using PowerShell Aliases: Best Practices

Anonymous — Mon, 08 Apr 2013 05:00:00 GMT

Summary: Microsoft Scripting Guy, Ed Wilson, demystifies some of the confusion surrounding using Windows PowerShell aliases.

Microsoft Scripting Guy, Ed Wilson, is here. “Don’t use aliases!” I hear this all the time from various people on the Internet. I am constantly asked at Windows PowerShell user groups, at TechEd, and at community events such as Windows PowerShell Saturday, if it is alright to use an alias.

What’s the big deal anyway?

An alias is a shortcut name, or a nickname, for a Windows PowerShell cmdlet. It enables me to type a short name instead of a long name. Is this a big deal? You bet it is. Windows PowerShell ships with around 150 predefined aliases. The longest cmdlet name is 30 characters long. Yes, that is right—30 characters. This is a very long command name. If I have to type New-PSSessionConfigurationFile very many times, I am definitely going to seek an alias. Luckily, npssc is available to do the job.

Note I used the following code to determine the length of cmdlet names and their associated aliases.

gal | select definition, @{label="length"; expression={$_.definition.length}} | sort length

What about tab expansion?

Tab expansion works to help to reduce the typing load when working with Windows PowerShell. One of the issues with tab expansion is that in Windows 8, there are over 2000 cmdlets and functions. Therefore, it takes more tabs to expand the correct cmdlet name. In the previous example, rather than having to type 30 characters to get access to the New-PSSessionConfigurationFile cmdlet, I can type New-P and hit the Tab key a few times. On my laptop, I have to press the Tab key four times before New-PSSessionConfigurationFile appears on the command line.

Typing five characters with New-P and pressing the Tab key four times is nine key strokes to enter the New-PSSessionConfigurationFile command. The npssc alias is only five key strokes, so I save four key strokes every time I use the alias instead of using Tab expansion.

Use aliases when working interactively at the console

For me, it is a best practice to use Windows PowerShell aliases when I am working interactively in the Windows PowerShell console. This is because it is the best way to reduce the amount of typing. It also reduces the amount of memorization needed. For example, is it Get-ChildItem or Get-ChildItems? I do not need to remember either one, because I can use LS, DIR, or GCI as an alias when calling that particular cmdlet.

Note One of the most basic mistakes I see with beginners who are just learning Windows PowerShell is that they do not use Tab expansion, nor do they use aliases. Instead they attempt to type the entire Windows PowerShell cmdlet name—and invariably, they get it wrong. So use aliases, or use tab expansion, but do not attempt to type the long cmdlet names.

In addition, if there is a Windows PowerShell cmdlet that I use on a regular basis that does not have a currently defined alias, I like to create an alias and store it in my Windows PowerShell profile. In this way, I make sure I have easy access to any Windows PowerShell cmdlet regardless of the length of the actual cmdlet name.

When not to use aliases

With all the goodness that aliases bring to the table, I might be inclined to use aliases all the time. There is a disadvantage, however. Aliases can be hard to read. Some aliases make sense: Sort for Sort-Object, Where for Where-Object. Others, such as sv, sbp, sc, and rv are rather obscure. One of the nice things about Windows PowerShell code is that it is very readable. Therefore, Get-Service does not need much explanation—it returns service information. But gsv, needs a bit of explanation before I know that it is an alias for Get-Service. So, what I gain in speed of typing, I loose in ease of understanding.

When working interactively at the Windows PowerShell console, the primary purpose is to accomplish something. I want to get the task completed accurately, and timely. I do not want to expend any extra effort to accomplish the task. When I close the Windows PowerShell console, everything I typed is lost (unless I have enabled the transcript or exported my command history).

On the other hand, when I write a Windows PowerShell script, the purpose is to have something I can use over and over again. So I am creating an artifact that has intrinsic value, and that I can use as a management tool. The goal here is reusability, not speed of development and execution. Therefore, I do not want to use aliases in my script because it hinders readability and understanding.

Note A fundamental tenant of script development is that the better I can understand my script, the fewer errors it will contain, and the easier it will be to fix any errors that may arise. In addition, because scripts are reusable, it also will be easier to modify the script in the future. Time spent in script development is an investment in the future.

This does not mean I have to give up the ease of using aliases when I am writing a Windows PowerShell script. I wrote a function that I include in my Windows PowerShell profile that replaces all aliases with the actual cmdlet name: Modify the PowerShell ISE to Remove Aliases from Scripts. In this way, I have the ease of being able to use Windows PowerShell aliases, with the readability of full cmdlet names later.

Join me tomorrow when I will talk about more cool Windows PowerShell stuff.

Ed Wilson, Microsoft Scripting Guy