PowerShell.org Logo

PowerShell.org

Community Hub

June Blender

Explore articles and content from this author

June Blender

7 articles published

• 8 min read

ValidateScript for Beginners

There"™s been a lot of chatter about in Scripting Games 2013 blog posts about the ValidateScript attribute. The chatter is, appropriately, confined to the advanced events ““ this sort of thing is not expected in a one-liner. But I thought I”™d take a minute and demystify it ““ and discuss an issue that it raises about when input should be rejected.
Let”™s start with a quick description of ValidateScript and its siblings. For help, see about_functions_advanced_parameters.

Read Article
• 3 min read

A Helpful Message about HelpMessage

The Scripting Games 2013 winners have not yet been announced, but for the 3rd year running, I’m in the lead for the “Learned Most from the Scripting Games” award. I’m making space for the prize on my bookshelf. Seriously, I play with PowerShell all the time and read lots of blogs, but nothing compares to looking at dozens of scripts and commands and seeing how people do things in the real world.
One of the practices I’ve noticed is use of the HelpMessage parameter attribute to document a parameter. It’s a real thing, but I didn’t know that anyone used it any more.
Here’s my help message about HelpMessage:
Don’t use it! Users can’t see it. It does no harm, but it has no value. Danger lurks in writing a HelpMessage instead of writing help that users can see. Write help that Get-Help gets, that is, XML help or comment-based help.
Here’s what I’m talking about. This code is valid. The language permits it. But it’s not useful. And I saw it in several of the advanced solutions.

Read Article
• 2 min read

Placing Comment-Based Help

What an amazing event. I’m now reading through each of the Advanced entries in a vain attempt to whittle the entries down to a short list. It’s an incredibly difficult task, which is testament to your skill and diligence. We are so lucky to have so many competent scripters in the community.
As I read through the comments on each script, I’ve noticed several that say:
“Help should be nested under the function to work properly.”
Au contraire! This is not true and I want to make sure that people who see this comment are not misled. The Windows PowerShell team designed comment-based help to be really flexible.
As I explained in about_Comment_Based_Help, you can put comment-based help for a function in one of three positions:

Read Article
PowerShell for Admins
• 9 min read

Event #1: Moving Old Files

As a celebrity judge, I’m not required to blog ““ I’m just here for my good looks :> – but I’m having a great time reading the blogs posted by the Expert Judges about the Event #1 candidate solutions.  Much of the judging is subjective, but I’ll add the criteria that I use to distinguish a working solution from a great solution.
Before I do, though, I want to congratulate everyone who submitted an entry. Most of the entries work and you probably learned just from playing with the challenge. Keep it up and come back year after year.
One hint to everyone: TEST! Most of the entries work, but many fail if the directory for the application (e.g. App1 in \NASServer\Archives\App1) does not already exist. And, a few fail with regular expression errors on the Replace operator (more in the blog). There are lots of great test strategies, but you can just run your code on file in your own directories or step through the code in the Windows PowerShell ISE debugger.

Read Article
• 4 min read

How to Name Your Help Files

The first challenge of Scripting Games 2013 is complete! Honestly, you win by getting the experience of playing. I hope everyone is in there voting and writing really constructive comments. I’ll get over there in a minute, but I wanted to make sure that I got this information out to everyone before I get involved in voting.
Everyone who writes shared Windows PowerShell cmdlets, functions, scripts, CIM commands, and workflows also writes help topics ““ or gets a friend or colleague to do it.
For scripts and functions, you can write comment-based help (aka “inline help”).  All parameters of the Get-Help cmdlet support comment-based help, including the new ShowWindow parameter, and by adding a URL to the first related link, you can support the Online parameter in comment-based help.
But XML help files are required to document cmdlets (C#), CIM commands, and workflows, and to support Updatable Help. If you’re delivering your content in a module, you typically want to use XML-based help topics.
When you create XML-based help topics, you need to put them where Get-Help looks and give them the name that Get-Help expects. Otherwise, Get-Help will not find the help topic.
Get-Help looks for the XML-based help topics for the commands in a module in language-specific subdirectories of the module’s installation directory.  This is generally well-known and an easy instruction to follow.
The naming guidelines are a bit trickier. In general (specifics follow), Get-Help expects the help topic for a command to be in a help file that is named for the file in which the command is defined, including the file name extension. When the commands in a module are defined in multiple assemblies or multiple CDXML files, the module must include a separate help file for each assembly or CDXML file.
The help file name format is: -help.xml
For example:

Read Article
• 4 min read

Name that Property

Challenge #1 of Scripting Games 2013 is coming to a close. I can’t wait to see the results! I solved both the Beginner and Advanced versions just for practice and I learned a lot along the way. They’re not easy, but if you haven’t yet tried them, go for it. And be sure to review the candidate solutions for new techniques.
In my last post, I showed a very easy way to create a custom object in Windows PowerShell 3.0 and I argued that returning a custom object is far better than returning formatted objects. But, when you are formatting or selecting properties from an existing object, you can customize the names of the properties and their values. This techique isn’t new to Windows PowerShell 3.0 ““ it works in all versions – but it’s really handy, and I’ve noticed that not a lot of people use it.
Let’s start by changing the name of a table column. In this case, the big boss wants a list of files and their attributes. Get-ChildItem (“dir”) just about does it, but the property name is “Mode,” not “Atrributes,” and the big boss is a picky dude.

Read Article
• 6 min read

PSCustomObject: Save Puppies and Avoid Dead Ends

Welcome to Scripting Games 2013. Here’s my favorite hint for improving your functions and scripts. Avoid writing to the console or formatting your output. Instead use PSCustomObject in Windows PowerShell 3.0 and leave the formatting to the end user.
Windows PowerShell provides lots of great ways to return the output of a command or function. You can write to the host program (Write-Host), write to a file (Out-File), and format your output to look really pretty (Format-*). But all of these techniques kill puppies and bring the pipeline to an abrupt halt.
“Puppies?,” you ask. Yes! Windows PowerShell MVP and Scripting Games 2013 Viceroy Don Jones (@concentrateddon) famously says that every time you use Write-Host, a puppy dies. So sad!
The Format cmdlets are almost as bad, although no deaths have yet been attributed to them. Instead, when you use a Format cmdlet, a huge STOP sign should appear warning you that you’ve brought the pipeline to a halt. Not technically, of course, but for all practical purposes.
To see what I mean, take a peek at these two commands. The output of these commands looks very similar, but it’s really quite different.

Read Article