Essential PowerShell: To alias, or not to alias, that is the question

Recently there was a discussion between community experts and a product team about a module they are working on.  The topic being discussed was cmdlet aliases: whether or not they should provide aliases for their cmdlets out of the box and if so, how they should be provided.  Aliases are great for ad-hoc PowerShell work, which is what most PowerShell users do at this point, and incredibly useful when you’re trying to put out a fire and managing your infrastructure using PowerShell.  However, there are many important things that module authors need to consider when planning aliases for their cmdlets, as follows:

1. There are many cmdlets out now, and more and more every month.  Coming up with a vsa (very short alias) that is unique is a challenge at best, and the more time goes by the more tla’s (three-letter aliases) will get used up.  The likelihood of an alias conflict is already high, and increasing all the time given the number of commands that are available both from Microsoft and from third party vendors.

2. The land grab with alias names is worse than it is with functions or cmdlets.  With functions or cmdlets, you can have multiple modules loaded with conflicting names and access either command using the fully qualified command name.  With aliases though you are not provided this same capability – there can be only one.  Aliases are simply commands set to a single value and they cannot be qualified using a module name qualifier to disambiguate if a name conflict arises.

3. Depending on how careful (or not) that developers are, it is very easy for a module author to completely take over (overwrite) an existing alias with no warning or message indicating that this has happened, resulting in potential command hijacking between module teams.  A simple call to Set-Alias does this without warning.  On the flipside, if developers don’t hijack aliases, then some of the aliases they would otherwise create may simply not be defined.

4. When aliases are hijacked, unloading a module doesn’t correct the problem because an alias that was overwritten by a module alias will simply become completely unavailable when the alias is removed as the module is unloaded.

As far as I am aware, this situation does not improve with the next version of PowerShell either, so it’s years away from getting better.

Believe it or not, even with these things in mind, I’m actually still pro aliases.  I just think that some extra care/thought needs to be put into their definition.  There is no real standard here that both satisfactorily addresses the issues identified above and that allows for consistency across companies/teams at this time.  Given that is the current state of affairs, if you are considering aliases for your module I recommend one of the following approaches:

1. [SAFEST] Rather than trying to come up with something that can be shipped despite these issues, at this time I think aliases would be best addressed in a "tips and tricks" type of blog post, proposing a short script that defines some useful aliases for the module/snapin in question in order to allow admins to be able to deal with fires quickly using ad-hoc PowerShell commands via some aliases.  Such a script should generate warnings whenever a name conflict is discovered so that users are aware when an alias either cannot be created or is overwritten.

2. [EXPERIMENTAL] Ship aliases with your module, but try to make sure they really are unique.  For example, if you’re a vendor whose company name starts with Q, you could prefix all of your aliases with "q".  This is attractive because there are no verbs that start with "q", so right from the start you’ve dramatically reduced the chance that you’ll have a conflict, setting yourselves up better to have aliases that belong to you.  Then you would only have to coordinate within your company to make sure the aliases used across teams are unique.  This isn’t foolproof though because there may be multiple products/vendors that adopt the same standard, and if the name of your company or product starts with G, the likelihood of a conflict would be much higher (the alias prefix used for "get-*" cmdlets is "g") so you may want to choose a pair of letters instead.  Regardless, you’ve likely reduced the risk, and you could generate a warning whenever you run into a conflict that prevents an alias from being created.

3. [RECOMMENDED] Lots of 1 and a little bit of 2: use unique alias names that work for your product team/company, but don’t ship them with the module.  Instead, push them out as a value add on a blog post, and see how the community responds.  At the same time work with MVPs and Microsoft to get these issues addressed such that a shorthand system for command names does work.  Some MVPs, already proposed a few things to the Microsoft PowerShell team that could help here (aliases for module names for one — think PS\gsv for a core PowerShell version of Get-Service or EX\gu for the Get-User cmdlet that comes with the Microsoft Exchange module or AD\gu for the Get-User cmdlet that comes with the Microsoft Active Directory module, and so on), but more discussions need to happen and this will take more time.

I recommend the third option because given the current issues with alias hijacking and with no support for disambiguation, it seems to be the best solution for now (from my perspective at least).  If you have come up with other alternatives that resolve these issues, please share them with the community so that this improves going forward.

Hope this helps,

Kirk out.

Essential PowerShell: Know your operator and enclosure precedence

PowerShell version 1 comes with a lot of operators, and the list becomes even longer in version 2 with cool new operators like -split and -join.  Whether you’re writing scripts or using PowerShell interactively, dealing with multiple operators in an expression that possibly contains different enclosures (brackets, quotation marks, etc.) as well can be very tricky.  It is very important to know how the PowerShell interpreter processes the expression so that you can get your expressions right the first time or, if you’re not so lucky, so that you can identify the problem in your expressions later and fix them. 

Recently there have been several posts on the forums where the problem has been a lack of understanding of the operator and enclosure precedence in PowerShell.  That’s not too surprising because the precedence order used by the PowerShell interpreter doesn’t seem to be documented at this time.  You can find the precedence order of arithmetic operators through the about_arithmetic_operators help file, you can find out some precedence details for specific operators in various operator help files, and you can find out the precedence of command types through the about_command_precedence help file, but that’s about it.  There is no single help file that documents the overall operator and enclosure precedence.  It doesn’t seem to be listed in any of the PowerShell books I have read either. 

Fortunately through some ad hoc experimentation and through some reading of the help documentation that does exist it is possible to figure out how all of this works.  I’ve gone through that exercise recently and the resulting table of operator and enclosure precedence is below.  Before getting to the table though there are a few important things I should mention, as follows: 

  1. Any items that share the same row in the table have the same precedence and are evaluated from left to right when adjacent within an expression unless otherwise indicated.
  2. The intent of this table is to identify a precedence that can be used to create or troubleshoot more complicated expressions without a lot of guesswork.  It is not intended to explain what each of the operators are and how you can use them (although to help understand expressions you might have to deal with I do mention a few details about some operators that function differently than the majority of operators in PowerShell).
  3. If you want to learn about the individual operators and see examples showing how they can be used I recommend you consult the about_operators help file and all of its related files.

With that out of the way, here is the operator and enclosure precedence table for PowerShell:

[] Type enclosures
Any character placed inside of these enclosures is treated as part of a literal type name.  The contents are not evaluated like an expression would be.
” “ Double-quoted string enclosures
‘ ‘ Single-quoted string enclosures
@” “@ Double-quoted here-string enclosures
@’ ‘@ Single-quoted here-string enclosures
 
{} Script block enclosures
 
() Nested expression enclosures
@() Array subexpression enclosures
$() Subexpression enclosures
 
. Property dereference operator
:: Static member operator
 
[] Index operator
 
[int]
[string[]]
etc.
Cast operators
Multiple adjacent operators in this row have a right-to-left evaluation.
-split (unary) Split operator (unary)
-join (unary) Join operator (unary)
These operators can be used as unary or binary operators.  Their precedence varies depending on how they are used.
, Comma operator
This operator is the array element separator.  It can be used as an unary or binary operator.
++ Increment operator
– – Decrement operator
These unary operators can be used before or after a variable or property.  When used before the variable or property (as a prefix operator), the value is incremented or decremented first and then the result is passed into the expression in which it is contained.  When used after the variable or property (as a postfix operator), the value is passed into the expression in which it is contained and then the variable or property is immediately incremented or decremented.
Negate operator
-not Not operator
! Not operator
-bnot Bitwise not operator
Multiple adjacent operators in this row have a right-to-left evaluation.
.. Range operator
 
-f Format operator
 
* Multiplication operator
/ Division operator
% Modulus operator
 
+ Addition operator
Subtraction operator
 
-split
-isplit
-csplit (binary)
Split operator (binary)
-join (binary) Join operator (binary)
-is Type is operator
-isnot Type is not operator
-as Type as operator
-eq
-ieq
-ceq
Equal to operator
-ne
-ine
-cne
Not equal to operator
-gt
-igt
-cgt
Greater than operator
-ge
-ige
-cge
Greater than or equal to operator
-lt
-ilt
-clt
Less than operator
-le
-ile
-cle
Less than or equal to operator
-like
-ilike
-clike
Like operator
-notlike
-inotlike
-cnotlike
Not like operator
-match
-imatch
-cmatch
Match operator
-notmatch
-inotmatch
-cnotmatch
Not match operator
-contains
-icontains
-ccontains
Contains operator
-notcontains
-inotcontains
-cnotcontains
Does not contain operator
-replace
-ireplace
-creplace
Replace operator
With the exception of the join operator and the type operators (-is, -isnot, and –as), each of the operators in this row has a case-sensitive and an explicit case-insensitive variant.  Case-sensitive variants are prefixed with c (e.g. -ceq) and case-insensitive variants are prefixed with i (e.g. –ireplace).
-band Bitwise and operator
-bor Bitwise or operator
-bxor Bitwise exclusive or operator
 
-and Logical and operator
-or Logical or operator
-xor Logical exclusive or operator
 
. Dot-sourcing operator
& Call operator
Unary operators that are only valid at the beginning of an expression, a nested expression, or a subexpression.
= Assignment operator
+= Assignment by addition operator
-= Assignment by subtraction operator
*= Assignment by multiplication operator
/= Assignment by division operator
%= Assignment by modulus operator
Multiple adjacent operators in this row have a right-to-left evaluation.

Since this table is created through experimentation and through snippets of information about precedence that I was able to find in the help files, it may not be entirely accurate.  If you find any problems with the precedence information provided here, please let me know and I’ll update this table accordingly. 

[Update 09-July-2009: Fixed table formatting, added an index operator, added all case-sensitive and case-insensitive variants and adjusted the precedence for the property dereference and static member operators.] 

Thanks, 

Kirk out. 

Share this post:

Essential PowerShell: Define default properties for custom objects

After posting my blog entry about naming your custom object types on Thursday, Hal Rottenberg left me a comment saying how it’s a shame that you have to manually create ps1xml files to store your type data and format data extensions.  Hal’s right.  Having to create ps1xml files to accompany each script you make that generates custom objects is too much work for the script author, and the script consumer has more files to download each time.  But then I thought twice about what Hal said, and asked myself: Is creating the ps1xml files to get the output you want from custom objects really necessary?

Fortunately the answer to this is “No”.  But why not?  Before I answer that, I should give a short explanation about how PowerShell determines what properties it will display when an object is output and in what format that object will be displayed.

How PowerShell determines the default format for an object

Let’s use the WMI service object for the Windows Update service as an example.  You can get this object in PowerShell using this command:

$object = gwmi Win32_Service -Filter ‘name=”wuauserv”‘

This command calls Get-WmiObject (using the gwmi alias) and requests the Win32_Service object that has the name “wuauserv”.  The result object is stored in the $object variable.

Now that the object is stored, if you want to view it you simply need to enter “$object” (minus the quotes) in your PowerShell console and you’ll see the default representation of that object.  It looks like this:

image

Here you can see the ExitCode, Name, ProcessId, StartMode, State and Status properties for the Win32_Service object.  There are many more properties than these six though.  You can type “$object | Format-List *” in PowerShell for yourself to see them all…there is quite a long list.  So how did PowerShell decide that these six properties were the ones to display by default?  In this case, the object itself contained the list of properties that would be displayed by default.  In PowerShell, any object may have the set of properties that will be output by default when that object is displayed stored in a member on the object itself.  It’s not kept in the most obvious of locations, but you can find it when you need to.

For any object in PowerShell, you can access its PSStandardMembers.DefaultDisplayPropertySet property to see the properties that are default for that object, if they are defined.  They won’t be defined for all objects, but in our example, they happen to be.  I show the results of the command to see the default property set here:

image

In this output window, the ReferencedPropertyNames property contains the list of properties that are displayed in PowerShell by default (ExitCode, Name, ProcessId, …).

What caused our object to display the properties in list format though?  After the default properties are set on an object (assuming they are set), when you output an object to the console without any Format-verb cmdlets at the end of the pipeline, the PowerShell formatting engine looks in the format data it has loaded and finds the first format data specification whose object type matches the one of the types in the object hierarchy that can be found by accessing the PSObject.TypeNames parameter.  It doesn’t matter if it is for a list format, a table format, a wide format, or a custom format — the first one found is used.  The types in the object hierarchy are looked up starting with the lowest derived type (index 0 in that collection) and then moving on to the next lowest (index 1), and so on until the base type is reached.

For our Win32_Service object, there is no format data specification for any of the object types, in which case PowerShell applies a default formatting rule: if there are four properties or less in the list of properties to display (the default properties if they were assigned, all properties if they were not), display the object in table format; otherwise, display it in list format.  For other types of objects there may be formatting data found, and when this happens the default properties are ignored and the default format is derived using the first matching format data specification.  This simplifies this whole process, but it should give you an idea how it works.

How to define the default properties for any object

Now that you have a general idea how formatting works, do you see the shortcut to defining the default output for custom objects you create?  Here’s a hint: it isn’t through the creation of a ps1xml file.

The easiest way to define the default output for a custom object is to add a PSStandardMembers member to the object and set the default properties in that member.  For objects that don’t have their default properties defined in a type data file, this is very easy to do.  Assume you have a script that generates and returns one or more custom objects with six properties: Name, Property1, Property2, Property3, Property4 and Property5.  Here’s a script to create one such object:

$myObject = New-Object PSObject
$myObject | Add-Member NoteProperty Name ‘My Object’
$myObject | Add-Member NoteProperty Property1 1
$myObject | Add-Member NoteProperty Property2 2
$myObject | Add-Member NoteProperty Property3 3
$myObject | Add-Member NoteProperty Property4 4
$myObject | Add-Member NoteProperty Property5 5

To view this object, enter $MyObject in the console.  Here is the default output for that object:

image

There are no default properties assigned for this object and there are no type data or format data for the object type, so PowerShell resorts to determining the output format based on the number of properties that the object has.  This is fine for one object, like we have here, but if you have a script that returns a collection of these, having their default output in list format does not give users of your script a very good user experience because it is very hard to find information in a long list of objects output in list format in PowerShell.  To show the objects in table format users can simply pipe them to the Format-Table cmdlet where they can specify the properties to show, but they shouldn’t have to do that.  Instead, you can update your script so that it specifies the default properties when these objects are created.  Here are the additional commands required to specify the default properties for our sample object:

$defaultProperties = @(‘Name’,’Property2′,’Property4′)

$defaultDisplayPropertySet = New-Object System.Management.Automation.PSPropertySet(‘DefaultDisplayPropertySet’,[string[]]$defaultProperties)

$PSStandardMembers = [System.Management.Automation.PSMemberInfo[]]@($defaultDisplayPropertySet)

$myObject | Add-Member MemberSet PSStandardMembers $PSStandardMembers

The first command sets the default properties.  Then in the next command we create a new property set containing those default properties.  With that property set, we can create the collection of member info objects we need.  And then once we have that collection we can add that as our member set to our object.

After you have done this your custom object will display the default properties you specified when you output it without any Format-verb cmdlets.  Here’s our $myObject default output after running the commands shown above:

image

That’s more like it!  Now we have a custom object with a predefined default property set, ready for users to start using, and our custom object still contains all of the properties for the object so that users can get additional fields if they want them!

Taking it further

Armed with this knowledge, you should be able to specify the default properties on any custom objects you create without using ps1xml files.  What if you wanted to take this further?  What functionality would be useful to have for this in a generic script so that you could get even more use out of it?

Using the knowledge derived above I was able to put together a script called Select-Member.ps1 that provides rich support for selecting the default properties for an object if none exist, or overriding the default properties for an object if they were defined in a type data file.  Select-Member can be used in a pipeline against a collection, or it can be used by itself passing the objects to process into the inputObject property.

Note that when you download this script, if you haven’t already you will also need to download Get-PSResourceString.ps1.  This is a simple utility script used to look up localized error messages, and it is used by Select-Member.

Here are the syntaxes supported by Select-Member:

Select-Member [-include] <string[]> [-exclude <string[]>] [[-inputObject] <psobject>]
Select-Member -exclude <string[]> [[-inputObject] <psobject>]
Select-Member -reset [[-inputObject] <psobject>]

The first variation allows you to specify which properties you want to include and optionally which properties you want to exclude.  If you exclude properties, those will be removed only after the list of properties to include have been processed.  Both the include and the exclude parameters support wildcards as well.

The second variation allows you to specify which properties you want to exclude from the default without including any parameters.

The last variation allows you to reset the object so that it will use the default property set as defined by the type data files and throw away any default property set that was added with Select-Member.

Here’s a screenshot showing some cool things you can do with this script and WMI objects:

image

Here’s another screenshot showing how you can get better formatting on ADSI objects:

image

Note that in both these examples, the value isn’t simply in being able to specify the defaults ad-hoc like this; format-table can allow you to specify which properties you see.  The real value lies in writing scripts or functions that output objects already formatted a certain way.  You could have a script that would set the default properties for a bunch of WMI objects you use, or a script that creates its own objects and outputs them with default properties defined.  There are other opportunities with this cmdlet as well, but this should get you started.

What’s missing from this?

The Select-Member script doesn’t yet support specifying the parameter sort order, nor does it support specifying the single default parameter that is used when using wide format.  These could be easily added in the future, and I will look into that as time permits.

Give feedback!

As with all scripts I write, I’d love to hear what you think.  Whether you use the simple solution to specify default properties for custom objects or the more advanced Select-Member script, let me know how well it works out for you.

Thanks,

Kirk out.

Share this post:

Essential PowerShell: Use non-portable console customizations sparingly

Isn’t it odd how issues with software are often raised in groups?  I’ve been helping people use software for a long time and I find it uncanny how when I come across an issue once, there are bound to be two or three other occurrences of the same issue just about to be brought to my attention.  Maybe it just seems that way because once I’m on track to discovering the issue I notice other occurrences of the same issue more easily.  All I know is that this happens all the time.

Recently one such issue came to my attention quite a few times and it needs to be talked about.  Any of the following questions were used by those facing the issue:

  • Why doesn’t this command work in that PowerShell console?
  • Why did my PowerShell script work when I ran it here but it doesn’t work when I run it there?
  • Why can’t I find command commandName?  It worked fine when I used it in the other console.
  • I used to be able to use drive driveName, but I can’t anymore.  Why?

The answer to these questions lies in the recognition of one area where PowerShell is not very consistent: through the use of customized PowerShell consoles.

Since PowerShell has been out now for over a year, many product teams now provide PowerShell snapins for their products.  This includes Microsoft products like Exchange, System Center Operations Manager, System Center Virtual Machine Manager, SQL Server and IIS (among others) as well as ISV products like VMware ESX and Server (the VI toolkit) and Quest ActiveRoles Server (the QAD cmdlets).  And there are others who provide PowerShell snapins for a particular business need, like SDM Software’s Group Policy Management Console (GPMC) Cmdlets, /n software’s NetCmdlets, and SoftwareFx’s PowerGadgets.  Many (the majority, in fact) of these snapins come with their own customized PowerShell console.  These customized console are designed to do one or more of the following:

  1. Display welcome text with help.
  2. Show a tip of the day.
  3. Run in elevated mode on Windows Vista and Windows Server 2008.
  4. Load the PowerShell snapin(s) relevant to the product that the shell customization came with.
  5. Change the current location to a provider that was included with the snapin(s) or a drive that was created within the customized shell.
  6. Create custom commands (functions and aliases) to make it easier to use the snapin(s).
  7. Prompt the user for connection-related information to establish a connection required for the cmdlets to work.

There are definitely other possibilities of how these customized consoles might be used, but this list gives you the general idea.  Most of these customizations are helpful because it gives the PowerShell newcomer a starting point; however, more than half of them can give users the wrong impression and cause them to ask the questions listed above when they use other PowerShell consoles.  Let’s look at some examples.

One thing in common among each of the customized consoles is that they load the PowerShell snapin(s) relevant to the product that the shell customization came with.  The Exchange Management Shell loads the two snapins that come with Exchange, so that users don’t have to do this to use Exchange cmdlets:

Add-PSSnapin -Name `
Microsoft.Exchange.Management.PowerShell.Admin
Add-PSSnapin -Name `
Microsoft.Exchange.Management.PowerShell.Support

This might not seem like a big issue, however in practice it seems to give users the false impression that they can simply call the cmdlets they need from any PowerShell script or console, which ultimately results in head-scratching when commands or a script don’t work somewhere else.  And as indicated, this is common among each of the customized consoles, so the IIS PowerShell Management Console, System Center Operations Manager Command Shell, Windows PowerShell with PowerGadgets, and others all do the same thing, loading their respective snapin automatically.

Another customization that seems to be common is for consoles to provide custom commands (aliases and functions) that are only available in that particular console.  VMware does this in their VMware VI Toolkit (for Windows).  When you open that console, you are presented with a message that shows you four commands as useful starting points, three of which only work in the VMware VI Toolkit (for Windows) shell (FYI, the commands I’m referring to are Get-VICommand, Get-VC and Get-ESX).  You can imagine that causes confusion when someone is trying to use one of these commands in another console.  Of course VMware isn’t the only one that does this.  The Exchange Management Shell creates three commands that are only available by default in that console (Get-ExCommand, quickref and Get-ExBlog) and the System Center Operations Manager Command Shell creates 10 commands that are only available by default in that console.  I won’t bother listing all of those here because I’m sure you get the picture by now.  Trying to use these commands in other consoles without adding them to the profile or explicitly creating them results in an error indicating that the command was not found and invariably some head scratching for the individual who is trying to run then.

A third type of customization is to check for the presence of a connection and then to prompt users for connection information if a local connection was not detected.  The System Center Operations Manager 2007 Command Shell provides connection management like this in its console.  The connection that is established is not usable outside of that console, nor is it documented accordingly, so users need to be aware that their scripts will have to include commands to make the required connections in order to work in any PowerShell environment.

There are surely going to be other examples of this as different teams customize their console environment to meet their needs.  As a PowerShell end user, when these customized consoles are very convenient, what can we do to make sure we’re aware of what customizations are being made?

Fortunately the console customizations are easy to discover.  Every customized console uses PowerShell’s command line parameters to perform the customizations.  This means viewing the properties of any of the shortcuts used to launch a customized console allows you to see what customizations are being performed by examining the command line parameters for powershell.exe.  The customizations that you need to look at are the PowerShell console file that is used (as identified by the -psconsolefile argument) and the script that is executed (as identified by the -command argument).  The PowerShell console file (psc1 file) is an xml document that defines which snapins should be automatically loaded by PowerShell when it starts.  The snapins identified in this file are silently added to the PowerShell session when it is opened.  The command argument identifies the PowerShell script or PS1 file that will be run after the snapins are loaded.  This script is used to customize the look of the console, create custom commands, manage connections, etc.

Now that you have this information, all you need to do is make sure you are aware of the customizations in the console you are using, particularly those that are not portable to other consoles, so that you don’t make incorrect assumptions when you write your scripts.

Before I close this off, I have a request that I’d like to put out there for snapin developers.  If you’re creating a customized PowerShell console when your snapin is installed, please make an effort to make those customizations self documenting.  I don’t want you to hurt the end user experience your after, but I think a bit of carefully worded output that identifies your console customizations as customizations that are specific to that console would go a long way to educate beginner PowerShell users about how consoles can be customized and what they need to be aware of when switching from one console to the next.  Without that information, users simply aren’t getting the information that they need to use your commands in other console that they might use.  And of course, if you are making custom function that are only available in your customized console, ask yourself, should those function only be available in one console, or should they be available all the time.  Often times I bet the answer is the latter, so please consider making cmdlets for those function you feel are necessary for the right experience when using your snapin.  Otherwise you’re just making it more difficult for your users to have the experience that you want them to have.

Thanks for reading!

Kirk out.

Share this post: