After working exclusively with PowerShell in my career for over two years now, it has become quite clear to me that the single most valuable feature in Microsoft Windows PowerShell, in my opinion anyway, is its extensibility.  In particular, it’s how easily it can be extended in PowerShell itself through a combination of PowerShell scripts and XML files, without the need of a compiler.  There are some features that are a very close second to that (consistency and discoverability), but the extensibility that PowerShell provides is truly second to none.

Version 1.0 of PowerShell was extendible from within PowerShell via combinations of PowerShell functions, the .NET Framework, WMI, ADSI, Add-Member and external ps1xml files that define type extensions and formats, not to mention snapins.  Using these features in PowerShell 1.0, I found them more than capable to allow me to create some really creative workarounds to some challenging issues that were identified in that version.  Not everything can be worked around, of course; some bugs can really only be fixed by the PowerShell team, and that will always be the case.  Those bugs aside though, PowerShell 1.0 really did a great job of providing a ton of functionality and enabling people like you and me to add even more.

Still, the solutions I could come up with in PowerShell 1.0 didn’t function quite the same as a regular PowerShell cmdlet.  There were some subtle differences and limitations in what you could do in that release.  Version 2.0 of PowerShell addresses some of those limitations, bringing even more extendibility options to the table with advanced functions, classes (using Add-Type), modules, and proxy functions.  These new options are a welcome addition to the PowerShell ecosystem and they allow me to ask the question “Why wait for PowerShell 3.0?”, a question I can now try to answer with creative solutions to problems in PowerShell and with creative ways to extend PowerShell so that you don’t necessarily have to wait for the next release to get new features or functionality that you might be looking for.  This article is the first in what I hope becomes a series of solutions that allow you to get some functionality you might find in PowerShell 3.0 without having to wait for it.

First on my list of areas needing improvement comes from a recent question that came up on a mailing list I follow:

I’m using Import-CSV to import a two-"column" CSV file and return a custom object with two additional properties. But I want the first property to be an Int and the second to be a DateTime. How do I do that? (I’ve tried several strategies, including explicit casting of the types in an array, but they come out as strings.

Import-Csv is a really, really handy cmdlet.  It allows you to import the contents of a csv (character-separated value) file as a collection of objects so that you can then do things with them.  It is commonly used in bulk provisioning or modification scenarios, where administrators can work with the data in the csv first if necessary and then write a script to do the required work according to the data from each entry in the csv file.

It has certain limitations, though, and those limitations can cause you to have to include additional complexity in your scripts to work around the limitations.  When you import data using Import-Csv, every property on the objects that are created are all of type string.  If you are trying to work with some properties containing dates (System.Datetime) or others containing numeric values or other types, complicated pipelines with manual conversion using ForEach-Object or Select-Object is required.  That’s fine for one-off scenarios, but this has come up before, and it makes sense for Import-Csv to allow users to set the types for the properties on the objects they are importing — that’s one problem to solve.

Another limitation is that objects imported from Import-Csv don’t necessarily have an appropriate type name associated with them.  If the file was created manually or by another program, the objects will be generic PSObjects.  If the file was created by exporting data from PowerShell using Export-Csv, a type may be included in the csv file but most csv files I work with come from sources other than PowerShell.  You can customize the object type name however you like (and this is recommended if you are doing something like Importing data from a csv file into the PowerGUI Admin Console so that you can then associate relevant actions with that object type), but again this isn’t something you would want to do each time you import csv data because it’s just that much more work.

It sounds to me like this user would have preferred being able to call Import-Csv using a syntax something like this:

Import-Csv C:\birthdays.csv -Type String,Int,Date

or, with a slightly more powerful example, perhaps like this:

Import-Csv C:\birthdays.csv -TypeMap @{Age='Int';Birthday=[System.DateTime]} -As 'BirthdayRecord' -UseETS -Overwrite

We could simply put in a feature request to the PowerShell Connect site (something I recommend you do whenever you come across something you feel is missing or incorrect), but that won’t do anything to help us today.  How can we solve those two problems now and bring Import-Csv into a level of functionality we might like to think we’ll get in PowerShell 3.0, like what is shown above, in such a way that getting typed objects with properly typed properties is as simple as importing data from a csv file using nothing but an Import-Csv command?  The answer to that comes from one of my new best friends in PowerShell: proxy functions.  The proxy function feature in PowerShell allows you to create an advanced function with the same name as a cmdlet that internally calls that cmdlet.  Since functions have a higher precedence that cmdlets in the command precedence order, you’ll always get the proxy function if it’s loaded when you are using the basic (that is to say, non-qualified) cmdlet name.

Creating a proxy function is easy.  All you have to do is execute a static .NET method called Create on the System.Management.Automation.ProxyCommand class and pass in a new System.Management.Automation.CommandMetaData object created by using the result of calling Get-Command for the cmdlet you want to proxy to get the internal script that will be the body of the proxy function, then wrap that in a function with the same name as the cmdlet you are proxying and then, to add that function to your current script file, output it to another file and then copy it over using an editor.  Huh?  That sure sounds complicated.  Well, since it’s not all wrapped up in a cmdlet for you, it is more complicated than it needs to be.

Let’s try that again.

Creating a proxy function is easy.  All you have to do is follow a few steps to get the command you need to run that generates the proxy function body, and then work within your favorite editor to copy that command body into your function in the file you are working on.  My favorite editor is PowerGUI, so I’ll use that in my example.  First, make sure you have installed PowerGUI with the new PowerShell 2.0 snippets (you can read more about those here) and then open up your PowerGUI Script Editor and follow these steps:

1. Select Edit | Insert Snippet.
2. Scroll down the list of snippets until you find a folder called “PowerShell v2” and double-click on it.
3. Scroll down the list of PowerShell v2 snippets until you find one called “function (proxy)” and double-click on it to insert that snippet.
4. In the snippet Name field, type in the name of the cmdlet you want to create a proxy for and hit enter.

If you like to learn by watching others, you can watch a demonstration of this (and other snippets) in a screencast that is posted on YouTube.  If you’re a keep-your-fingers-on-the-keyboard junkie like me, you can use shortcuts and type in the snippet folder and name and get this done very quickly.  When you’re done, you’ll have a function that looks something like this:

<#
    For more information about proxy functions, see the following article on the
    Microsoft PowerShell Team blog:

        http://blogs.msdn.com/powershell/archive/2009/01/04/extending-and-or-modifing-commands-with-proxies.aspx
#>

function Import-Csv {
    <#
        To create a proxy function for the Import-Csv cmdlet, paste the results of the following command into the body of this function and then remove this comment:
        [Management.Automation.ProxyCommand]::Create((New-Object Management.Automation.CommandMetaData (Get-Command Import-Csv)))
    #>
}

That’s not exactly a proxy function yet.  There’s one more step you need to take, as described in the comment inside the proxy function.  That comment indicates you need to run the command inside it and paste the results of that command over the comment itself.  Copy the command as described in that comment and paste it in the embedded PowerShell Console window that is docked in your PowerGUI Script Editor, and once you have it pasted there, run it by pressing enter.  The result of that command is string output that will become the main body of your proxy function.  If you did this for Import-Csv like I did, it will look like this:

[CmdletBinding(DefaultParameterSetName='Delimiter')]
param(
    [Parameter(ParameterSetName='Delimiter', Position=1)]
    [ValidateNotNull()]
    [System.Char]
    ${Delimiter},

    [Parameter(Mandatory=$true, Position=0, ValueFromPipeline=$true, ValueFromPipelineByPropertyName=$true)]
    [Alias('PSPath')]
    [System.String[]]
    ${Path},

    [Parameter(ParameterSetName='UseCulture', Mandatory=$true)]
    [ValidateNotNull()]
    [Switch]
    ${UseCulture},

    [ValidateNotNullOrEmpty()]
    [System.String[]]
    ${Header})

begin
{
    try {
        $outBuffer = $null
        if ($PSBoundParameters.TryGetValue('OutBuffer', [ref]$outBuffer))
        {
            $PSBoundParameters['OutBuffer'] = 1
        }
        $wrappedCmd = $ExecutionContext.InvokeCommand.GetCommand('Import-Csv', [System.Management.Automation.CommandTypes]::Cmdlet)
        $scriptCmd = {& $wrappedCmd @PSBoundParameters }
        $steppablePipeline = $scriptCmd.GetSteppablePipeline($myInvocation.CommandOrigin)
        $steppablePipeline.Begin($PSCmdlet)
    } catch {
        throw
    }
}

process
{
    try {
        $steppablePipeline.Process($_)
    } catch {
        throw
    }
}

end
{
    try {
        $steppablePipeline.End()
    } catch {
        throw
    }
}
<#

.ForwardHelpTargetName Import-Csv
.ForwardHelpCategory Cmdlet

#>

Select all of that text that was output in your docked PowerShell Console window and copy it to your clipboard.  Then paste it over the original comment that told you to do this.  Now you have a proxy function.  It doesn’t do anything different than the cmdlet you are proxying yet, but when it is loaded in your PowerShell session it will proxy that cmdlet properly.

So now you might be saying to yourself: “That’s great (although the process could be a little more streamlined…), but now what do I do?”.  Now you can add your own parameters that you wish were on the original cmdlet in the first place, making the proxy function much more powerful.  For our example with Import-Csv that I showed earlier, I would like to be able to specify the type of the properties in the csv file, either as an array when I want to specify all property types or as a hash table when I only want to specify a type for a few named properties, knowing that the rest will default to string.  I’ll accomplish that by adding a Type and a TypeMap parameter to my Import-Csv proxy function.  I’d also like to be able to specify the type of the object that is imported using Import-Csv, and I’d like to be able to define whether my type name should be treated as an Extended Type Name extension as well as whether or not the current type hierarchy should be overwritten or not.  I’ll accomplish that by adding As, UseExtendedTypeSystem (alias UseETS), and OverwriteTypeHierarchy parameters.

Those changes will allow me to use the syntax I proposed above without waiting for someone else to give it to me.  By taking the time to create the proxy function that supports these parameters I’ll save myself and others time and complexity in the scripts they write by moving all of the extra pipeline complexity that would otherwise be necessary directly inside the proxy function.  It is worth noting that a proxy command isn’t as efficient as it would be if the added functionality were included in the cmdlet itself, but that’s not the point.  The point is that you can extend cmdlets when they leave you wanting more today rather than waiting to see if PowerShell 3.0 includes the extensions you want or not tomorrow (or three years from now, who knows when it will be released).

The resulting proxy function is a pretty good sized function, but we’ve added quite a few features to it as well, and those features need to have some logic to support them.  I’m including my version of the Import-Csv proxy function at the bottom of this post in its entirety so that you can give it a try yourself and see if it helps you out.  With the exception of the parameter definitions I added to the param statement, all logic supporting the new parameters I have added is enclosed in collapsible regions so that you can see the specific locations where I inserted my logic.  That should make it a little easier for you to see how logic can be added within a proxy function, enabling you to experiment a little and create your own PowerShell 3.0 flavors of your favorite cmdlets.  If you prefer to download the ps1 file containing the proxy command directly, I have also shared that on my SkyDrive, here.

There are several other important things I should mention about proxy functions, as follows:

1. You can add parameters, modify parameters, remove parameters, or leave parameters unchanged in proxy functions.
2. If you add parameters, you need to remove them from the parameter collection ($PSBoundParameters) before you create your wrapped command so that those parameters are not passed to the cmdlet you are proxying.  You may also have to do this if you modify parameters, depending on the modifications you make.
3. If you find you are adding pipelines to certain commands you call on a regular basis, it is likely a sign that the cmdlet itself needs improvement.  Consider creating proxy functions in these situations so that you don’t have to do as much typing in the long run.
4. If you create and use proxy functions, share them with the community so that the PowerShell team can see where cmdlets could be improved.  You can’t influence what goes in PowerShell 3.0 if you’re not sharing.

Here’s the final version of my Import-Csv proxy function:

#Requires -Version 2.0

function Import-Csv {
    <#

    .ForwardHelpTargetName Import-Csv
    .ForwardHelpCategory Cmdlet

    #>

    [CmdletBinding(DefaultParameterSetName='Delimiter')]
    param(
        [Parameter(ParameterSetName='Delimiter', Position=1)]
        [ValidateNotNull()]
        [System.Char]
        ${Delimiter},

        [Parameter(Mandatory=$true, Position=0, ValueFromPipeline=$true, ValueFromPipelineByPropertyName=$true)]
        [Alias('PSPath')]
        [System.String[]]
        ${Path},

        [Parameter(ParameterSetName='UseCulture', Mandatory=$true)]
        [ValidateNotNull()]
        [Switch]
        ${UseCulture},

        [ValidateNotNullOrEmpty()]
        [System.String[]]
        ${Header},

        [ValidateNotNullOrEmpty()]
        [System.String[]]
        ${Type},

        [ValidateNotNullOrEmpty()]
        [System.Collections.Hashtable]
        ${TypeMap},

        [ValidateNotNullOrEmpty()]
        [System.String]
        ${As},

        [Alias('UseETS')]
        [ValidateNotNull()]
        [Switch]
        ${UseExtendedTypeSystem},

        [ValidateNotNull()]
        [Switch]
        ${OverwriteTypeHierarchy}
    )

    begin {
        try {
            $outBuffer = $null
            if ($PSBoundParameters.TryGetValue('OutBuffer', [ref]$outBuffer)) {
                $PSBoundParameters['OutBuffer'] = 1
            }
            $wrappedCmd = $ExecutionContext.InvokeCommand.GetCommand('Import-Csv', [System.Management.Automation.CommandTypes]::Cmdlet)

            #region Initialize helper variables used in the processing of the additional parameters.
            $scriptCmdPipeline = ''
            #endregion

            #region Process and remove the Type parameter if it is present, modifying the pipelined command appropriately.
            if ($Type) {
                $PSBoundParameters.Remove('Type') | Out-Null
                $scriptCmdPipeline += @'
 | ForEach-Object {
    for ($index = 0; ($index -lt @($_.PSObject.Properties).Count) -and ($index -lt @($Type).Count); $index++) {
        $typeObject = [System.Type](@($Type)[$index])
        $propertyName = @($_.PSObject.Properties)[$index].Name
        $_.$propertyName = & $ExecutionContext.InvokeCommand.NewScriptBlock("[$($typeObject.FullName)]`$_.`$propertyName")
    }
    $_
}
'@
            }
            #endregion

            #region Process and remove the TypeMap parameter if it is present, modifying the pipelined command appropriately.
            if ($TypeMap) {
                $PSBoundParameters.Remove('TypeMap') | Out-Null
                $scriptCmdPipeline += @'
 | ForEach-Object {
     foreach ($key in $TypeMap.keys) {
        if ($TypeMap[$key] -is [System.Type]) {
            $typeObject = $TypeMap[$key]
        } else {
            $typeObject = [System.Type]($TypeMap[$key])
        }
        $_.$key = & $ExecutionContext.InvokeCommand.NewScriptBlock("[$($typeObject.FullName)]`$_.`$key")
    }
    $_
}
'@
            }
            #endregion

            #region Process and remove the As, UseExtendedTypeSystem and OverwriteTypeHierarchy parameters if they are present, modifying the pipelined command appropriately.
            if ($As) {
                $PSBoundParameters.Remove('As') | Out-Null
                $customTypeName = $As
                if ($UseExtendedTypeSystem) {
                    $PSBoundParameters.Remove('UseExtendedTypeSystem') | Out-Null
                    $customTypeName = '$($_.PSObject.TypeNames[0] -replace ''#.*$'','''')#$As'
                }
                if ($OverwriteTypeHierarchy) {
                    $PSBoundParameters.Remove('OverwriteTypeHierarchy') | Out-Null
                    $scriptCmdPipeline += @"
 | ForEach-Object {
     `$typeName = "$customTypeName"
     `$_.PSObject.TypeNames.Clear()
    `$_.PSObject.TypeNames.Insert(0,`$typeName)
    `$_
}
"@
                } else {
                    $scriptCmdPipeline += @"
 | ForEach-Object {
     `$typeName = "$customTypeName"
    `$_.PSObject.TypeNames.Insert(0,`$typeName)
    `$_
}
"@
                }
            } else {
                if ($UseExtendedTypeSystem) {
                    $PSBoundParameters.Remove('UseExtendedTypeSystem') | Out-Null
                }
                if ($OverwriteTypeHierarchy) {
                    $PSBoundParameters.Remove('OverwriteTypeHierarchy') | Out-Null
                }
            }
            #endregion

            $scriptCmd = {& $wrappedCmd @PSBoundParameters}

            #region Append our pipeline command to the end of the wrapped command script block.
            $scriptCmd = $ExecutionContext.InvokeCommand.NewScriptBlock(([string]$scriptCmd + $scriptCmdPipeline))
            #endregion

            $steppablePipeline = $scriptCmd.GetSteppablePipeline($myInvocation.CommandOrigin)
            $steppablePipeline.Begin($PSCmdlet)
        }
        catch {
            throw
        }
    }

    process {
        try {
            $steppablePipeline.Process($_)
        }
        catch {
            throw
        }
    }

    end {
        try {
            $steppablePipeline.End()
        }
        catch {
            throw
        }
    }
}

Are you still with me?  Whew, if you stuck with me this far, thanks!  There’s a lot of information here, and while it’s definitely not something for a beginner, if you’re comfortable experimenting in PowerShell I encourage you to give proxy functions a try and see what solutions you can come up with.  Or, if you don’t mind taking the time to leave me a note, let me know what your biggest pains are with cmdlets today that you think could be solved with proxy functions and I’ll see what I can do to help create solutions for those.  The feedback system really works, so don’t be shy, participate by either sharing solutions or letting others like me know what your problems are so that we can continue to help evolve PowerShell into the best scripting environment out there!

Thanks for listening!

Kirk out.

Share this:

Learning and using PowerShell v2 features just got easier!  Earlier this week I uploaded a collection of PowerShell v2 code snippets to the PowerGUI website, and they are ready for you to download and use.  All you need to do is follow the installation instructions in the snippet document.

Once you have the snippets installed, watch the screencast that demonstrates how you can learn more about some PowerShell v2 features by using the v2 code snippets.  You can watch it in flash format with a table of contents, or you can watch the YouTube version below.

Want to see more snippets?  Let me know which areas of PowerShell you would like to see covered in snippets by leaving me a note in the comments.

Enjoy!

Kirk out.

Share this post:

Last week Microsoft made the announcement that Windows Server 2008 R2 reached RTM.  Among the many cool new features provided with that release (Hello?  PowerShell v2?  Need I say more?), Microsoft has now added a recycle bin feature to Active Directory.  The management interface provided by Microsoft for this feature is the command line, or more specifically, PowerShell.  That’s great if you’re like me and you love to manage your infrastructure using PowerShell, but what if you prefer a GUI?  Fortunately there is a solution for you too.

As Jackson Shaw suggested on his blog about a week ago, PowerGUI provides an admin console that allows you to create your own management UI that is layered on top of PowerShell.  This admin console can be extended with PowerPacks, which are essentially add-ins that provide additional user interface elements in PowerGUI that invoke PowerShell script when clicked.  All you need to do is add the user interface elements you want and then provide the scripts to power those elements, managing the Active Directory Recycle Bin objects or anything else you need to manage.  Or alternatively you can check to see if someone on the PowerGUI Community like myself has already created a PowerPack with the functionality you are looking for.

In the case of the Active Directory Recycle Bin, you’re in luck.  I just finished creating the first release of a new PowerPack that is designed to allow you to manage any objects in your recycle bin.  You can find the Active Directory Recycle Bin PowerPack by following the hyperlink here or by going directly to http://www.powergui.org and browsing into the Active Directory subcategory in the PowerPack Library.  This PowerPack includes the following features:

• View the contents of the recycle bin, including hierarchies
• Restore individual items in the recycle bin (recursively or not) to their original location
• Restore individual items in the recycle bin (recursively or not) to a specified location
• Permanently delete objects in the recycle bin (recursively or not)
• Empty the contents of the recycle bin
• Modify the number of days that the recycle bin is configured to retain objects and the number of days that objects are to be kept in a tombstone state before permanent deletion

If you would like to see a demo of the Active Directory Recycle Bin PowerPack, watch this screencast:

If you prefer watching a high resolution version of the screencast, you can watch it in flash format here or on YouTube directly in HD format here.

This is the initial release of this PowerPack and it contains a good amount of new functionality.  If you are experimenting with the Active Directory Recycle Bin feature, please take a look at this PowerPack and provide any feedback you have so that we can continue to provide improvements that are valuable to you and others in future releases.

Thanks for listening!

Kirk out.

Share this post:

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:

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:

It is not uncommon to want to store the results of a command in an array so that you can refer to the contents of that array later in your script.  This is often done by simply assigning the results of a command to a variable.  For example, if you were importing the contents of a csv file into an array you might do it like this:

$collection = Import-Csv C:\newusers.csv

Commands like this will work forever as long as you have a csv file in the appropriate location.  Occasionally though you may find that a script containing this command just stops working.  It might not make sense to you at the time because the script hasn’t changed, so what’s the problem?

The problem is that in the above command there is no guarantee that $collection will actually store an array of objects because there is no guarantee that Import-Csv will return more than one object.  In fact, there is no guarantee that Import-Csv will return any objects at all.  If the C:\newusers.csv file is generated by some other tool, it is possible that it might contain 0, 1 or more entries.  When it contains 0 or 1 entries, the $collection variable will either be $null or it will contain one object representing the single entry in the C:\newusers.csv file, respectively.  If further down in your script you’re always treating $collection as if it is an array and using indices to access elements in the array, your script will suddenly start failing with errors.

Fortunately there is a way to ensure that the results of any command are stored in an array.  All you need to do is wrap the command that returns the object(s) in array enclosures, like this:

$collection = @(Import-Csv C:\newusers.csv)

If you take this approach in your script and then later when you run your script C:\newusers.csv only contains one entry or perhaps doesn’t contain any entries at all, your $collection variable will still be an array so that you can check the size using the Count property ($collection.Count), access individual values using indices (e.g. $collection[0]), etc.  This is a much safer practice to take when writing your scripts so that you can make sure that you have an array when you store an array.

Of course if you are dealing with very large collections of objects that aren’t already loaded in memory an even better practice is to avoid storing the entire collection in memory altogether by using pipelines and cmdlets like ForEach-Object to process the items in the collection, but I wanted to make sure you were aware of how you should properly handle and store arrays in variables in your scripts so that you’re not facing a script long after it has been written and asking yourself why it suddenly stopped working.  There are plenty of other reasons why a script could stop working at some point but at least now you’re armed with the knowledge required to avoid one of those possibilities.

Kirk out.

Share this post:

Another week has gone by and I have another brand new PowerPack ready for download.  This time around it’s the Org Chart PowerPack.  This is a PowerPack that I put together based on a Get-OrgChart function I wrote to analyze org chart data at work.  It lets you do some really cool things such as:

1. Dynamically create an org chart from users in Active Directory using title, department, office, address, and other properties.
2. Generate a Visio Org Chart from PowerGUI for the any branch of an organization.
3. Create statistical reports for the employees in your organization to see breakdowns of employees by office, department, management, etc.
4. Dynamically generate Office Directory reports in HTML when using it in conjunction with the Advanced Reporting PowerPack.

Note: The Org Chart PowerPack uses the Quest AD cmdlets to retrieve information from AD so you will need to install those first before you can use the PowerPack.

If you would like to see how this PowerPack can be of benefit to you, check out this screencast:

This screencast was recorded in HD format so you can click on the HD button once you start watching it to enable high definition video.  Alternatively, if you would prefer to watch a high resolution flash version with a table of contents you can watch the screencast here.  I decided to try widescreen format this time since that is my format preference…let me know if this is a problem for you.

This is the first release of this PowerPack and I’m anxious to hear what you think so please give it a look and share your feedback so that I can improve it with another update in the future.

Thanks for listening!

Kirk out.

Share this post:

In PowerShell you can pass pipeline data to parameters that are not configured to accept pipeline input using ScriptBlock parameters.  This has been discussed before and it is well worth your time to make yourself familiar with that capability of PowerShell because it allows you to create true one-liners in places where you might think you cannot.  Basically it boils down to this: you can pass a script block into parameters in a cmdlet that is not of type script block and within the script block you provide the $_ variable will contain the object that was just passed down the pipeline.  The script block will be evaluated first, and then the result will be passed into the cmdlet parameter.

Still, even with that knowledge in hand people often trip over the ScriptBlock parameter syntax when using a parameter that takes a hash table (aka an associative array) as input.  The most common example I can think of where this is encountered is in the Quest AD cmdlets.

Many of the Quest AD cmdlets have a parameter called ObjectAttributes.  This parameter serves two purposes: in Get cmdlets it is used to define the values you want to filter on; in Set and New cmdlets it is used to define the values you want to assign to specific attributes.  Not consistent, I know, but that’s a whole other discussion.  In both cases the ObjectAttributes parameter is a hash table and to use it you simply need to define a hash table that matches attribute names with values.  Here’s an example showing how users trip over the syntax without realizing it:

Get-QADComputer Comp1 `
    | Set-QADObject -ObjectAttributes ` 
        @{userAccountControl=$_.userAccountControl -bxor 2}

This one liner was designed to enable or disable a computer object in AD.  It will run without raising an error, and it will even enable or disable the computer object, but it will not work like you might expect.  After running this command the userAccountControl attribute (which contains many flags, not just a flag for enabled/disabled state) will not be properly configured.  Why?  It looks like it is properly using a ScriptBlock parameter, but it is not so the $_.userAccountControl value will either evaluate to 0 if the $_ variable is null or if it does not have a userAccountControl property, or it will contain the userAccountControl value from whatever object the $_ variable contained before you called Get-QADComputer in the first stage of this pipeline.  Nothing in this command instructs PowerShell to treat the ObjectAttributes parameter as a ScriptBlock parameter.  So what’s missing?

The most important thing to remember about ScriptBlock parameters is that they always must be surrounded by script block enclosures (“{“ and “}”).  Otherwise they are not script blocks.  In our example above it looks like the parameter is surrounded by the proper enclosures, but that’s not true.  It’s surrounded by hash table enclosures (“@{“ and “}”), and this is what trips people up when working with this syntax.  To make this be properly treated as a ScriptBlock parameter, we need to surround the hash table with curly braces, like this:

Get-QADComputer Comp1 `
    | Set-QADObject -ObjectAttributes ` 
        {@{userAccountControl=$_.userAccountControl -bxor 2}}

That makes PowerShell recognize that we have a ScriptBlock parameter and the $_ variable within it properly evaluates to the object that just came down the pipeline.  No ForEach-Object or temporary variables required.  It seems simple enough when explaining it but you’d be surprised how many people get tripped up on this syntax.

If you want to see some forum discussions where this has been an issue for others, you can go here or here.

Kirk out.

Share this post:

]]> http://poshoholic.com/2009/06/23/powershell-quick-tip-setting-ad-object-attributes-with-scriptblock-parameters/feed/ 0 Poshoholic http://poshoholic.com/2009/06/20/just-released-advanced-reporting-powerpack/ http://poshoholic.com/2009/06/20/just-released-advanced-reporting-powerpack/#comments Sat, 20 Jun 2009 09:40:27 +0000 Kirk Munro http://kirkmunro.wordpress.com/2009/06/20/just-released-advanced-reporting-powerpack/ ]]>

I just published a brand new PowerPack to the PowerPack Library called the Advanced Reporting PowerPack.  If you’ve been keeping your eyes on the Virtualization EcoShell project as well as PowerGUI, you may have already come across this PowerPack because I released it there first.

The Advanced Reporting PowerPack allows you to generate HTML reports with collapsible nested groups for any set of data in PowerGUI.  Think VMs, Snapshots, AD Users or Groups…you name it.  If you can get the data into a grid in PowerGUI, you can generate a nice HTML report using this PowerPack.  The only UI element this PowerPack adds to PowerGUI is a common action called “Create report…”.  This action does all of the heavy lifting to generate a cool HTML report for the items you have selected.

Want to see what how to get started using this PowerPack?  Watch this screencast:

If you would prefer to watch a higher resolution version, you can watch the screencast in flash format here.

This is only the first release of advanced reporting functionality in PowerGUI and already it’s really powerful.  Still, there is room for improvement so if you have any feedback, please share it with me in my comments or on the PowerGUI Forums so that I can consider it for the next release!

Thanks and enjoy!

Kirk out.

Share this post:

While I was at tech·ed 2009 last week I ran into Hal while he was waiting for Scott Hanselman to finish up a game of Rock Band so that he could participate in a session for Scott’s popular podcast, Hanselminutes.  Hal asked me if I wanted to participate, to which I said absolutely yes, and the result is a 35 minute discussion with Hal, Scott and I about PowerShell 2.0.

Hal’s an IT pro, and while I work with IT pros a lot these days I have a developer background, so we were able to speak to both sides of the fence and talk about why you should pay attention to PowerShell whether you’re a software developer or an IT pro.

That recording is now live, so if you want to hear it head over to Hanselminutes Show #162: PowerShell 2.0, and let me know what you think afterwards.

Kirk out.

Share this post:

Here’s a great question that someone just posted today on the PowerGUI forums:

I have the latest verions of the Quest AD cmdlets, PowerGUI and the Active Directory PowerPack.  Can I use PowerGUI to search for old computer accounts?  For example: computer accounts that haven’t had their machine account password reset for over three months?

The timing of this question is perfect because the update of the Active Directory PowerPack that I posted two weeks ago allows you to do this without having to write any scripts yourself.  For those of you who want to try this but don’t have the most recent versions of PowerGUI, the Quest AD cmdlets and the Active Directory PowerPack installed, follow those links and download and install those before continuing.  Installation instructions are on the appropriate web pages where necessary.

Once you all of the necessary software installed, here’s what you need to do.

Step 1: Add the attributes you need to the list of attributes retrieved from Active Directory.

There are In the PowerGUI Admin Console, expand the “Active Directory” node and click on “Configuration”.  This will show you the current domain that PowerGUI will gather data from.  You can change this if you like, however you don’t need to unless you want to use alternate credentials or connect to another domain.  With the configuration showing in the grid, click on the “Manage default attributes” link.  That will present you with a view something like this:

This shows you the current list of attributes that are retrieved for each individual Active Directory object.  This will be initially configured with the default attributes as defined by the Quest AD cmdlets plus a few attributes that are required for the Active Directory PowerPack.  You can add whatever attributes you want to gather here for any of the object types.  To help solve our immediate problem and be able to get a list of computer accounts that have not had their machine account password reset for over three months, we need to add the pwdLastSet attribute for computer objects.  To do this, simply click on the “Add attribute…” action, provide the name of the pwdLastSet attribute in the “Attribute name” field and set the “Retrieve attribute for computer objects” value to True.  When you click on OK, that attribute configuration will be saved and any computer objects retrieved using the Quest AD cmdlets will have that attribute retrieved with them.

Step 2: Retrieve the objects you want from Active Directory and optionally show the attributes you want to filter on.

Once you have configured PowerGUI so that it will retrieve the pwdLastSet attribute for computer objects, you need to get your computers.  You can do this by simply clicking on the “Computers” child node under the “Active Directory” node.  This will present you with a list of computer accounts, showing their Name, Type and DN by default.

With the list of computer objects showing, you can optionally add the pwdLastSet attribute to the view by right-clicking in the column headers and selecting “More…” from the menu that appears.  With the list of all attributes that can be added showing, scroll down until you find the pwdLastSet attribute and check the checkbox beside it.  Then click on OK to save that change and your pwdLastSet attribute will be retrieved with your computer objects from the Computers node.

Step 3: Create a client-side filter to filter out the objects you don’t care about.

With the list of all of your computer objects showing, you can create a filter to reduce the number of objects to those that you need to see.  To do this, click on the Filters button above the column headers.  This will make the filter panel visible.

You can use this panel to filter any collection based on the properties of the objects in that collection.  For our particular problem, we want to see computer objects whose password has not been changed in the last 3 months.  We can get that by selecting “pwdLastSet” in the “Property” field, “Less or equal” in the “Operator” field, and selecting the calendar date three months ago in the “Value” field using the calendar control.  Once that is set, click on the “Apply” button to apply the filter and your list of computer objects will be filtered to only show those whose machine passwords haven’t changed in the last 3 months.

Step 4: Make the newly filtered data set available in its own node.

Now that you have the data you’re looking after, your “Computers” node is now configured to always show you the filtered list because PowerGUI remembers the filters you apply to nodes.  You might not like this configuration, preferring to have a separate node to view the data that you want.  Fortunately, PowerGUI lets you do create that easily too, and you still don’t have to do any scripting.  To create a separate node that lets you get the same data set, simply click on the “Save As…” button in the filter panel.  This will allow you to save the script from the Computers node with the filter you have created automatically applied as a client-side filter for that script.  Simply give the new script node a name (something intuitive like “Computers with old passwords” will do), and click on OK to save the new child node.  Then you can click on the “Clear All” button in the filter panel for your “Computers” node because that filter will no longer be needed.  Now click on your new node and you’ll get the list of computers you are after, and it will look something like the screenshot below.

Step 5: Make your work reusable at any time by taking it one step further.

At this point you have successfully created a new node that gets specifically the data you were looking for and you didn’t have to do any scripting to get it, which is great!  You can make it a little better still though.  For our specific problem that we’re trying to solve, we created a new node that reports any computer object with a machine account password that hasn’t been changed within 3 months from today.  But tomorrow that will be come 3 months and 1 day.  The next day that will become 3 months and 2 days.  What if you want to customize the node so that it reports computers whose machine accounts have not had their passwords changed in the last 3 months, no matter what day you click on it?  For that to work you will have to do a minor script modification.

Right-click on your new “Computers with old passwords” node and select properties.  This will show you the script used to retrieve your computers and filter the list.  At the very end of that script, you will see something like the following:

func_Computers | Where-Object {
    $_.'pwdlastset' -le [System.DateTime]"2009-02-08"
}

The Where-Object cmdlet contains the filter that is excluding any computers whose pwdLastSet attribute is greater than 3 months from the day we did this (for me that that’s February 8, 2009 since I created the node on May 8, 2009).  To change that filter so that it always works using a date 3 months earlier than now, you simply need to replace [System.DateTime]”2009-02-08” with (Get-Date).AddMonths(-3).  That changes the end of our script to this:

func_Computers | Where-Object {
    $_.'pwdlastset' -le (Get-Date).AddMonths(-3)
}

That’s it!  A simple replacement of the filter condition and you’re off and running with a brand new node designed to meet your specific needs with PowerGUI, the Quest AD cmdlets and the Active Directory PowerPack!

In a future article I’ll show you just how simple it is for you to take a collection of extensions to PowerPacks that you have created like this and package them up in a PowerPack so that you can share them with other users in the Community as well!

Enjoy!

Kirk out.

Share this post:

This is about what can happen when things go wrong and what not to do so that things don’t go wrong.

In case you didn’t know, I work at Quest Software on the PowerGUI Team.  My position is rather unique because I work exclusively with Windows PowerShell, and I don’t think there are too many jobs out there that offer that experience.  The main focus of my job is to create and extend PowerPacks, which are collections of PowerShell scripts that are packaged together to define an extension to the customizable PowerGUI Admin Console.  The scripts in the PowerPacks I create range anywhere from the extremely simple (one cmdlet or function call) to the very complicated (a script that calls into one or more functions that span many thousands of lines of PowerShell script).

Among others, one of the PowerPacks that I manage is the Active Directory PowerPack.  The Active Directory PowerPack provides a management interface to Active Directory, and it uses the Quest AD cmdlets in its PowerShell scripts to do the actual management of Active Directory.  For quite a few reasons¹,  I need to explicitly indicate which connection should be used when you use that PowerPack to do something with Active Directory, regardless of what it is you are doing.  This means I am absolutely dependent on being able to determine what connection should be used in any script that is included in the PowerPack.  For scripts that are used at the beginning of a pipeline I look for the appropriate connection information that is stored globally.  For other scripts that are used later in a pipeline with Quest AD cmdlets I look at the Connection property that is attached to the objects coming down the pipeline.  This model has worked very well until recently when something unexpected happened.

Almost two weeks ago, just after version 1.2 of the Quest AD cmdlets was released, it came to my attention that the Connection property that I am so dependent on was not included on objects in that release.  For those of you who are not developers, this type of change (changing a public interface in an SDK) is very bad news.  It is called a breaking change, and the name is very fitting – the Active Directory PowerPack started breaking all over the place for users who upgraded their Quest AD cmdlets to version 1.2!

Amid a flurry of email discussions between myself and the Quest AD cmdlets team I spent the next week and a bit putting together an update to the Active Directory PowerPack so that it would work despite these changes, basically putting the Connection property there myself if it isn’t there.  At the same time, the Quest AD cmdlets team quickly started work on a 1.2.1 patch release to put the Connection property back in so that scripts outside of PowerGUI that use that property wouldn’t be affected either.  The patch for the Quest AD cmdlets is not available yet, but the updated Active Directory PowerPack, and the updated Network PowerPack which also used the Quest AD cmdlets a fair amount and was therefore susceptible to this change, are now posted in the PowerPack library and available for download.  If you use these PowerPacks, I strongly recommend you download and import the most recent releases of each of these PowerPacks.  Their document page in the PowerPack library contains all of the information you need to upgrade your PowerPacks and get started using the new versions.

Now that I have finished dealing with the impact of a breaking change like this one and the unpleasant work that ensues,  I thought it would be worthwhile to share with others what exactly consititutes a breaking change in a PowerShell cmdlet or advanced function.  The following is a list of 13 rules that you should adhere to when updating your cmdlets or advanced functions if you want to avoid introducing breaking changes:

1. Do not remove any published parameters that are included in your published cmdlets or advanced functions.
2. Do not rename any published parameters that are included in your published cmdlets or advanced functions unless you add an alias to the parameter that is the old parameter name.
3. Do not reduce or remove pipeline support for any published parameters in your published cmdlets or advanced functions that support pipeline input.
4. Do not remove support for $null input for any published parameters in your published cmdlets or advanced functions that support $null input.
5. Do not modify the default value for any published parameters in your published cmdlets or advanced functions unless that modification will not change how the command functions in existing scripts.
6. Do not add a required flag to any parameter in published parameter sets in your published cmdlets or advanced functions.
7. Do not modify the position of any published parameters in published parameter sets in your published cmdlets or advanced functions.
8. Do not replace the associated object type with an incompatible type for any published parameters in your published cmdlets or advanced functions.
9. Do not remove wildcard support for any published parameters in your published cmdlets or advanced functions that have wildcard support.
10. Do not remove support for building the value from the remaining arguments in any published parameters in your published cmdlets or advanced functions that support building the value in this manner.
11. Do not remove any of your published parameters from published parameter sets in your published cmdlets or advanced functions.
12. Do not increase validation restrictions for any of your published parameters in your published cmdlets or advanced functions that have validation restrictions.
13. Do not modify or remove aliases for any published parameters in your published cmdlets or advanced functions.

Additionally you need to pay attention to the objects that are returned by your cmdlets or advanced functions so that you don’t introduce breaking changes on those either.  The following rules should be adhered to in order to avoid breaking changes on objects returned by your cmdlets or advanced functions:

1. Do not remove a public property or method.
2. Do not replace the types associated with a public property or method with incompatible types.
3. Do not modify the order of the parameters in a public method.
4. Do not add required parameters in a public method.

Not following these rules means risking breaking production scripts, risking making your customers unhappy, and many other potential undesirable consequences.  Please, if you are seriously trying to add value to the PowerShell ecosystem by extending it with additional commands, pay attention to these rules and don’t introduce breaking changes when you update them!

Thanks for listening!

Kirk out.

Share this post:

Wow, have I been busy.  In case you hadn’t noticed from my blog posts late last year and early this year, I’ve been working very hard at putting together multiple back-to-back updates for the VMware Infrastructure Management PowerPack for the past several months.  This has involved working long hours with many thousands of lines of PowerShell script and figuring out how to do some really cool things with both PowerShell and VMware’s PowerCLI (formerly known as the VI Toolkit).  The end result is always fulfulling, and I’m usually pretty good at setting up the really cool functionality so that I can leverage it in any PowerPack so all my hard work pays off in the long run.

A few weeks ago I finished off yet another update with some really cool new features, however this update isn’t available for the PowerGUI admin console just yet.  That update is coming shortly after we release the next version of PowerGUI, which has some functionality that it is dependent on.  If you can’t wait until then though, you can take a look at the new functionality now as part of the first public beta release of the Virtualization EcoShell that came out on April 15th.

What is the Virtualization EcoShell?  The Virtualization EcoShell is a project started by Scott Herold that was designed to provide an administrative experience that is tailored for virtualization administrators.  It is powered by PowerGUI and comes with a script editor and an admin console just like PowerGUI.  The out of the box experience is different though because it doesn’t come with PowerPacks for Exchange and Active Directory.  Instead it includes functionality that virtualization administrators care most about.  At the moment this is simply the VMware Infrastructure Management PowerPack, but over time this will grow to include other virtualization-related administrative functionality (think: additional VMware features, functionality to work with virtualization platforms from other vendors, and capabilities to extend into important technologies surrounding virtualization such as storage).

If you want a preview of the next generation of the VMware Infrastructure Management PowerPack a little early as well as a look at a new virtualization administration platform, all you have to do is pop over to the Virtualization EcoShell site and download it.  You can install and use it side-by-side with PowerGUI, so you won’t need any secondary systems or a VM to run it on either.  Once you’ve taken a look, let us know what you think or what you would like to see next on the forums!  Your feedback directly influences the features we add, and we’re listening!

Kirk out.

Share this post:

The PowerGUI VMware Infrastructure Management PowerPack seems to be really popular with people, so I’ve been spending a lot of time over the past four months significantly enhancing that PowerPack.  Some of the enhancements are things that we wanted to put in and others are things that community members had requested (note to the reader: if you like a particular PowerPack and would like to see it improved, speak up on the PowerGUI Forums…we really take your feedback very seriously! ).  Today I just finished posting another release of the VMware Infrastructure Management PowerPack with a few more enhancements, and I’m particularly happy with this one.

This release greatly improves usability through the new icons that were added (and I mean *greatly* improves…the value the icons add is huge).  It’s also the first PowerPack release that takes advantage of some really cool Visio scripts that I’ve been working on.  The Visio scripts I’m referring to were largely inspired by Alan Renouf’s vDiagram script, although the Visio script I ended up with doesn’t look anything like the original.  I’m itching to talk more about those scripts, but I want to write a blog post specifically on that topic so watch for more on this soon.  For now I’ll simply point out that to use the Visio functionality, you have to download the additional VESI_Visio.zip file that was added to the VMware Infrastructure Management PowerPack document page and install it as per the instructions in that document (see the “How to enable vDiagram support” section).  Visio 2007 is required.

For those of you who were fortunate enough to attend VMworld Europe in Cannes at the end of February, this release contains the icons and Visio features that Scott Herold was showing off during that show.  You can see a live demo of the new features on Scott’s website, here.

If you want to learn more about this PowerPack, including version history and other details, you can go here.  You can download the PowerPack from that location as well.

Kirk out.

Share this post:

The following question recently came up on a mailing list I follow:

When I am trying to get the definition for the alias "?", I need to escape it because if not it works like a wildcard.  That is ok.

But why do I have to use SINGLE quotes, and why do DOUBLE quotes fail to escape?  I thought it should be the other way around.

For example, this works:

Get-Alias ‘`?’

This does not work:

Get-Alias "`?"

Why?

This question was prompted by Aleksandar’s blog post about the problem.  There are quite a few things to consider here to understand what is going on.

First, as the author of the question pointed out, in the Get-Alias cmdlet the question mark character is a wildcard character.  That means if you simply call Get-Alias with a question mark (Get-Alias ?), you will get all one-character aliases because the question mark will match any character.  That will happen regardless of whether you use single quotes, double quotes, or no quotes.  So the question mark must be escaped to tell Get-Alias to treat it as an actual question mark, and not a wildcard question mark.

Second, in PowerShell a single-quoted string is a literal string, so characters are taken as is.  A double-quoted string is a special string where the contents are evaluated to determine what the actual string is (see Get-Help about_quoting_rules for more details).  In a double-quoted string, any variables or subexpressions (identified by their prefix of $) are evaluated and the results are placed in the string.  Also, any escaped characters are evaluated and the results are placed in the string.  The standard way to escape a character is to precede it with a backtick (`).

Third, if you escape any non-escape character by preceding it with a backtick, the result is simply that non-escape character.  The backtick is discarded.

Fourth, there is a difference between escaping escape characters when evaluating a double-quoted string and escaping wildcard characters in cmdlet that accept strings containing wildcards.  Both are escaped the same way, but understanding the timing of their evaluation and knowing what characters they consider to be escape characters is very important.  Double-quoted string evaluation happens outside of a cmdlet, before it is called.  Wildcard string evaluation happens inside of a cmdlet, once it is called.

And lastly, Get-Alias works just like the Path parameter set variant of Get-Item (that is to say, it works just like Get-Item when you call Get-Item with the Path parameter), returning multiple results when unescaped wildcard characters are in the search string and there are multiple matching aliases.  Get-Alias is a little simpler to use on a general basis, but if it wasn’t there you could just use Get-Item instead.

Now that we’re armed with that knowledge, lets break down the command we’re having a hard time with.

Get-Alias "`?"

Here are the results of that command in PowerShell:

What’s happening here?  When this command is executed, the first thing PowerShell has to do is evaluate the double-quoted string and get the result string that comes out of that evaluation, before the cmdlet is called.  As I explained above, any non-escape character that is escaped in a double-quoted string is simply evaluated as the non-escape character.  In our string, the question mark is being escaped, but that isn’t an escape character when it comes to string parsing (use the command Get-Help about_escape_character to get the list of escape characters in double-quoted strings), so the result of the evaluation is simply ‘?’.  When that string is then passed to Get-Alias, the Get-Alias cmdlet thinks we’re looking for any single-character aliases, so that’s what it gives us in the output.

What we need to do is make sure that the results of the evaluation of the double-quoted string are such that the question mark is preceded by a backtick so that it is escaped when it is passed into the Get-Alias cmdlet (string evaluation timing is important, remember?).  To do that, we need to know how to generate a single backtick in the result returned from a double-quoted string evaluation.  The backtick is an escape character itself as well as the character used to escape other characters (we learned this when we looked at the about_escape_character helpfile, mentioned earlier), so we can create a backtick in a double-quoted string by escaping it with itself, like this: "“".

Now that we know how to escape the backtick so that it is passed into the Get-Alias cmdlet, we can change our problematic command we were using by escaping the backtick in the double-quotes and get the results we wanted in the first place:

It is important to note that a non-quoted string is treated as a double-quoted string in PowerShell when it is evaluating a command that it is about to run, so if you wanted to do this without quotes at all, you would still have to escape the backtick, like this:

The last thought I want to leave you with is about Get-Item.  I mentioned earlier that Get-Alias works just like the Path parameter set variant of Get-Item.  Both of these need to have wildcard characters escaped if you want to find an alias that contains a wildcard character.  What I didn’t mention is that Get-Item has something that Get-Alias does not: a LiteralPath parameter set variant.  The easiest way to retrieve an alias containing a wildcard without worrying about escaping any characters is to simply use Get-Item with the alias PSDrive, like this:

This method requires the use of the LiteralPath parameter name and the alias PSDrive name, but it gives you exactly what you want, without having to worry about most of what I tried to show you here, and it’s easy.  Still, I had to show you the details first…a solid foundation in understanding how these things work goes a long way when writing and troubleshooting PowerShell scripts.  If you want it even easier, you could create a simple Get-LiteralAlias function that removes the need to use the Alias PSDrive name and calls Get-Item using the LiteralPath parameter set variant behind the scenes.  You could also create a Get-Alias function that has a Literal switch parameter so that you could simply indicate whether you wanted to call Get-Alias or Get-LiteralPath behind the scenes.  With PowerShell, there are definitely no shortage of options when you don’t have the functionality you are looking for the way you expect it to be there.  I’ll leave the exercise of creating the functions up to you, if you think it’s worth it (after all, there is only one default alias with a wildcard character in its name).

Armed with all of this knowledge, it becomes completely obvious why an unusual alias created with the New-Alias command (which doesn’t support wildcard characters) like this:

$foo = ‘bar’
New-Alias "“?$foo" ‘bar’

can be retrieved using either of the following Get-Alias commands:

Get-Alias "““?$foo"
Get-Alias "““`?$foo"

Right?

Kirk out.

Share this post:

I was just reading Steve Murawski’s latest blog post which contains a script called ConvertTo-Function that allows you to generate a function from a script file.  The intent is to allow you to have scripts you don’t call as often, and therefore don’t load into your profile, but when you need them you can use this script to easily generate functions that wrap them so that you don’t need to think about the path beyond the initial call to the ConvertTo-Function script.  That’s one way to facilitate this, but I have something I use quite commonly in my own environment that works much better for me for this scenario: aliases.

Aliases can reference a path to a script file.

This capability is often overlooked because aliases are most commonly used and thought of as terse command names.  Using them to reference a path to a script file is quite useful because it allows you to keep all of your scripts, complete or in development, in a common location.  You can control which ones are loaded in your profile by only creating aliases for those scripts.  Alternatively, for scripts that you really don’t use very often, you could have a function in your profile to create the aliases to those scripts on an as needed basis (which sounds a little like the Add-Module capabilities in PowerShell v2).  In either case, using aliases to reference script files is very handy because you don’t need to worry about whether the scripts you want to invoke are in a folder in your path environment variable or not.  You simply need to create an alias to the full path and then you can use that alias to invoke your script.

For example, assuming you had a script with the path C:\MyScripts\Miscellaneous\Do-Something.ps1, you could invoke it using the absolute or relative path, or if C:\MyScripts\Miscellaneous happened to be in your path environment variable you could simply invoke it using the Do-Something command.  But if you don’t have your script path in your path environment variable and/or you don’t want to change that variable, aliases give you the same capability on a temporary basis for your current PowerShell session (and only in your current scope by default if you want it really temporary).  Using our example script path, all you would have to do is create a new alias with this command:

New-Alias Do-Something C:\MyScripts\Miscellaneous\Do-Something.ps1

That allows you to invoke your script any time you want to by simply using the Do-Something alias, as long as it is created and visible in the current scope.

Kirk out.

Share this post:

Hot on the heels of the new release of the VMware VI Toolkit, I just finished uploading version 2.1 of the VMware Infrastructure Management PowerPack for PowerGUI.  This PowerPack facilitates management and automation of VMware Infrastructure servers using the VMware VI Toolkit with PowerGUI’s extendable administrative console.

Version 2.1 of the VMware Infrastructure Management PowerPack includes the following highlights:

• Significant performance improvements when loading datacenters and clusters.
• New top-level container nodes to facilitate viewing objects without having to browse into the Managed Hosts node.
• Links allowing you to browse into log files from hosts.
• Support for the VMware VI Toolkit 1.5 release.
• VMotion support for virtual machines.

In addition to these changes, several links have been added and quite a few defects have been fixed.

You can learn more about this PowerPack, including version history and other details here.  You can download it from that location as well.

As always, feedback on this PowerPack and all others is welcome and appreciated.  If you want to see something in the PowerPack, just ask!  You can either contact me directly (see my about page), or you can post your request using the PowerGUI forums.  We’re listening!

Kirk out.

Share this post:

(aka How to add C-style __LINE__ and __FILE__ macros to PowerShell)

When troubleshooting PowerShell scripts, it can be useful to log, store or output the current line number and and file name position so that you know where your script was when something happened.  This information is given to you automatically when there is an error, however if you’re not facing a PowerShell error but you have a problem with the logic in your script, you need to manually retrieve it from PowerShell.

The MyInvocation variable was designed for this purpose, providing you with details about the invocation of the current script or function as well as details about the current command that you are executing.  The trouble is that when you use $MyInvocation directly in a script file, the details it provides are about the invocation of the script, meaning the command used to invoke the script, and not about the current line within the script.  Fortunately, though, as with many things PowerShell there is a way.  To be able to use $MyInvocation to retrieve details about the current line in a script, you need to wrap it in a function and call that function.  When you do this, $MyInvocation will give you details about the command used to call the function that contains it, and if that command is inside a script file the details will include the script file name as well as the line number of the command.

Armed with that knowledge, you can create a few useful functions in your profile, and they will allow you to retrieve the current file name and line number from within any script you use.  Here are my interpretations of those functions:

#region Script Diagnostic Functions

function Get-CurrentLineNumber {
    $MyInvocation.ScriptLineNumber
}

New-Alias -Name __LINE__ -Value Get-CurrentLineNumber –Description ‘Returns the current line number in a PowerShell script file.‘

function Get-CurrentFileName {
    $MyInvocation.ScriptName
}

New-Alias -Name __FILE__ -Value Get-CurrentFileName -Description ‘Returns the name of the current PowerShell script file.‘

#endregion

A few good uses for these functions might be:

1. In complicated scripts where you want to verify the order of execution of certain lines of script.
2. When you are returning a value in multiple locations and you would like to simply know which location you returned from while troubleshooting without stepping through any lines in your script.

I hope this is useful for you.  I just started using these functions and they are already coming in quite handy for me.

Enjoy!

Kirk out.

Share this post:

Were you  curious what was hiding inside that gold box in the  PowerGUI train?  Keeping with the spirit of giving, I just finished publishing version 2.0 of the VMware Infrastructure Management PowerPack.  A lot of effort went into this PowerPack, which ended up including a complete restructuring of the elements in the tree, as well as the addition of a lot of new functionality that was not available in previous versions, all for free just like the many other PowerPacks that are available for PowerGUI.

A few highlights in this version include:

• Easy management of multiple VMware Virtual Center, ESX, ESXi or Virtual Server hosts from within one console.
• Single sign-on to multiple hosts that use the same credentials.
• Support for browsing through any of the inventory hierarchical views that are available in Virtual Center.
• Management of virtualization elements within one host or across many hosts through the same set of links and actions.
• Reporting and management of sessions, datacenters, clusters, resource pools, hosts, folders, virtual machines, templates, snapshots, networks, datastores, files, tasks and log files.

You can learn more about this PowerPack, including version history and other details here.  You can download it from that location as well.

Still not convinced you should give the VMware Infrastructure Management PowerPack a look?  Below you can click on a few screenshots to get a taste of what you’ll find if you do.

Browsing the Virtual Center hierarchy while managing snapshot files

Managing host sessions

Managing virtual machines

Looking into log files

If you manage VMware hosts or if you are interested in writing scripts against VMware hosts using PowerShell, I strongly encourage you to give this PowerPack a look.

As always, feedback on this PowerPack and all others is welcome and appreciated.  If you want to see something in the PowerPack, just ask!  You can either contact me directly (see my about page), or you can post your request using the PowerGUI forums.  We’re listening!

Happy Holidays everyone!

Kirk out.

Share this post:

I was recently working on a function where I had to convert objects to a type that was passed into the function when I came across something that may surprise some people.  Assuming you have a type stored in $type, what is the difference between the following two commands (other than style):

1. $result = Invoke-Expression “[$type]`$value”
2. Invoke-Expression “`$result = [$type]`$value”

I don’t have any prizes for this, but I thought it was worth asking just for fun.  I’ll post the solution after people have had some time to take a crack at it.

Solution

It’s been long enough to let people chew on this, so I can share the solution.  Only two people came back to me indicating that they had figured it out: Arnoud Jansveld and Thomas Lee.

The key difference between these is in how data is assigned to the $result variable when using an array.  In the first case, Invoke-Expression returns the converted $value (after it has been case to $type), but that return $value is then implicitly sent to Out-Default, which returns generic objects (boxing), so in the end if you started with an array you have a collection of objects (System.Object[]).  In the second case, the assignment is done inside of Invoke-Expression, before any boxing would occur.  Once the assignment is done, nothing is returned from Invoke-Expression, and you end up with an array of the type you were expecting.

This was just a silly little exercise, but it illustrates an important concept in PowerShell by showing how objects coming out the end of a pipeline are boxed in generic System.Objects.  That knowledge comes in handy from time to time when you are scripting, so it is worth remembering.

Enjoy!

Kirk out.

Share this post:

I recently published a new screencast on the PowerGUI Documentation page called “Introduction to the Hyper-V PowerPack“.  If you want to learn a little bit about what this PowerPack can offer you and how you can get started using it, take a few minutes and watch the screencast today!

In case you haven’t had a chance to see some of the functionality that this PowerPack provides you with, I’m including a few screenshots below to give you a quick preview.  Or, if you want to see the list of custom functions that drive the functionality in this PowerPack, read my blog post titled, “Use PowerPacks to Learn PowerShell“.

Managing VMs using the Hyper-V PowerPack:

Managing Snapshots using the Hyper-V PowerPack:

Kirk out.

Share this post:

The Hyper-V PowerPack for PowerGUI that I published last month is one of my favorite PowerPacks so far.  It’s a great example of how you can take a task that is pretty complicated for someone who doesn’t program for a living (like using PowerShell to manage Hyper-V via WMI), simplify it with rich PowerShell functions that look and feel like cmdlets, and then build a user interface on top those functions to perform management and automation tasks.  Since all of the PowerShell script behind the PowerPack is freely available through the PowerGUI Admin Console, using a PowerPack like the Hyper-V PowerPack is a great way to learn PowerShell because it allows you to get familiar with how specific administrative tasks translate into PowerShell scripts that you can then use for automation, provisioning, scheduled tasks, etc.

The scripts powering the Hyper-V PowerPack are particularly interesting because there are no cmdlets available yet to manage Hyper-V unless you use Microsoft System Center Virtual Machine Manager 2008.  The prescribed way to manage Hyper-V via script with the release of Windows Server 2008 is WMI.  Since working with WMI directly is not much fun after you have become spoiled with the ease-of-use you get with PowerShell cmdlets, not to mention quite difficult, I have included a lot of useful functions (over 30 of them so far) that wrap the WMI management code inside of a cmdlet-like experience complete with support for pipelining so that you can write scripts to work with your Hyper-V servers much more easily.  Here’s a complete list of the functions that are included in the current revision of the Hyper-V PowerPack:

Job Management

Get-HyperVJob
Wait-HyperVJob

Server Configuration

Get-HyperVServerSettings
Set-HyperVServerSettings

Service Management

Get-HyperVService

Physical Network Adapter Management

Get-HyperVPhysicalNIC
Set-HyperVPhysicalNIC

Virtual Network Management

Get-HyperVVirtualNetwork
New-HyperVVirtualNetwork
Remove-HyperVVirtualNetwork
Rename-HyperVVirtualNetwork
Set-HyperVVirtualNetwork

Virtual Machine Management

Checkpoint-HyperVVirtualMachine
Export-HyperVVirtualMachine
Get-HyperVVirtualMachine
Import-HyperVVirtualMachine
New-HyperVVirtualMachine
Remove-HyperVVirtualMachine
Rename-HyperVVirtualMachine
Restore-HyperVVirtualMachine
Set-HyperVVirtualMachine

Virtual Network Adapter Management

Add-HyperVVirtualNIC
Get-HyperVVirtualNIC
Remove-HyperVVirtualNIC
Set-HyperVVirtualNIC

Virtual Ide Drive Management

Add-HyperVVirtualIdeDrive

Virtual Scsi Drive Management

Add-HyperVVirtualScsiDrive

Snapshot Management

Get-HyperVSnapshot
Set-HyperVSnapshot
Remove-HyperVSnapshot
Rename-HyperVSnapshot
Update-HyperVSnapshot

Virtual Hard Disk Management

Get-HyperVVirtualHardDisk
New-HyperVVirtualHardDisk

These functions do not provide comprehensive coverage of all Hyper-V features and there are many more that I plan to add in a future update, but it’s well on it’s way to becoming a comprehensive set of functions.  If you are looking for specific functionality that doesn’t appear to be available through these functions, I encourage you to take a look at the methods on the rich objects that are output by these functions.  There is a whole lot more functionality available than you might think!  I just haven’t had time to expose all of the method-based functionality as cmdlet-like functions yet.

To use these functions in your own scripts you simply have to copy them out of the Hyper-V PowerPack.  Be sure to keep an eye on dependencies and make sure you get all the functions you need.  Most of the PowerPacks I’ve been working on lately come with useful functions like this, for the explicit reason that I want people to be able to use them inside and outside of PowerGUI.  I’ll blog about them as time permits, but until I make time for that I wanted to at least make you aware that they are there as a resource and as a learning tool.

If you want to write PowerShell scripts to manage your Hyper-V servers, doing yourself a favor to take a look at the Hyper-V PowerPack and the functions that it contains.  They might go a long way to helping you get your work done faster and more easily, either by using the functions themselves in your scripts or by looking at the PowerShell code behind the functions and learning how to get WMI to do what you want to do.

Kirk out.

Share this post:

Since the Hyper-V PowerPack for PowerGUI was published several weeks ago, I have found and fixed several defects, particularly in the area of adding and removing managed Hyper-V servers.  I have also enhanced the search functionality so that it is easier to use when you work with one domain in particular.  To see the complete list of changes, see the revision history section on the Hyper-V PowerPack page.

If you downloaded the Hyper-V PowerPack before Friday, November 14, 2008, I recommend that you visit the Hyper-V PowerPack site and upgrade your PowerPack to the most recent version.  Upgrading the Hyper-V PowerPack can be done in a few easy steps, as follows:

1. Download the new version of the PowerPack.
2. Open the PowerGUI Admin Console if you haven’t already.
3. Right-click the Hyper-V folder at the root of the Hyper-V PowerPack in PowerGUI and click on Delete.
4. Right-click the root node in the PowerGUI tree, click on Import, and select the updated HyperV.powerpack file that you downloaded.

Once you have done these steps, you will be using the most recent version of this PowerPack.  If you have any feedback or questions you would like to raise for this PowerPack or any others, please feel free to contact me directly (see my about page for details) or leave me a note on the PowerGUI Forums.

Enjoy!

Kirk out.

Share this post:

About three months ago I decided to go on a deep technology dive, exploring a facet of some technology with PowerShell and seeing what made it tick.  Typically these sorts of things take anywhere from a few days to a few weeks to work out the details and the end result is some useful scripts that I then blog about and try to leverage with a PowerPack or two.  Well this time I ended up going a little deeper than I have in the past, and I decided to go silent on my blog while I worked out the PowerShell scripts behind this huge project.  Today I’m happy to end that silence by sharing with you the largest PowerPack that has been published to date!

As of today, PowerGUI users can download a free Hyper-V PowerPack for PowerGUI!  This PowerPack has been a huge undertaking, to put it mildly, and I’m absolutely thrilled with the end result (and so happy that I’ve finally finished the first version…whew)!  Here’s a list of some of the key features that this PowerPack provides:

1. Bulk management of multiple VMs, Virtual Networks, Virtual Hard Drives, Snapshots, etc. within one Hyper-V servers and across multiple Hyper-V servers.
2. Support for remote management of Hyper-V servers using alternate credentials.
3. Integrated management of standard Windows features like Processes, Services, Event Logs, etc.
4. Automatic credential caching (in memory, not to disk) allowing you to enter a password for a Hyper-V server you are managing only once per PowerGUI session.
5. Discovery of Hyper-V servers through Active Directory.
6. Over 30 rich user-defined functions that wrap the Hyper-V WMI interfaces and provide a cmdlet-like experience when scripting with Hyper-V while outputting rich, custom objects complete with properties and methods to script to your heart’s content.  Many of these functions support CSV input through Import-Csv, so there are a lot of opportunities for provisioning already available.
7. 101 links and actions allowing you to manage just about everything you would want to manage in Hyper-V, including configuration of security via AzMan Scopes, Snapshot refresh, and many, many more.

In terms of Hyper-V functionality, the PowerPack is pretty comprehensive at this point.  There are some features that I have support for in functions that I just didn’t have time to put into the PowerPack at the end of this cycle.  There are also quite a few features in the PowerPack that aren’t available in the Hyper-V Manager.  But that just means there are opportunities for new features to be added in later versions of this PowerPack.  Let me know what features are the most important to you so that I can help you meet your Hyper-V management/scripting needs.

To give you an idea of what it took to make this PowerPack, the main script that contains the function library I’m using in this PowerPack is over 9500 lines long (if you’re new to PowerShell, that’s a heck of a lot of code in a language that lets you do so much with very, very short scripts)!  This huge script, and the scripts powering the links and actions, plus the rest of the PowerShell script behind the PowerGUI PowerPacks are all visible to the end user.  If you’re trying to figure out how to do something with Hyper-V via WMI and you can’t find the answer, take a look at the functions I have and see if they are already doing what you want to do.  Then you can use the functions or try to copy out the code that you need and go from there!

Just a quick note to get you started, once you download and import the PowerPack into PowerGUI, expand the Hyper-V node and then click on Managed Hyper-V Servers.  That will expose the Add Connection functionality you need to use to add your first connection to a Hyper-V server.  Once you’ve done that, you’ll be able to use the rest of the functionality against that server.

If you have any feedback for this PowerPack (or any others), feel free to leave a note on my blog or on the PowerGUI discussion forums.  We’ll be sure to try and help you meet your needs any way that we can!

So what are you waiting for?  Go to the Hyper-V PowerPack site and download the PowerPack today!

Kirk out.

Share this:

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:

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:

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:

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:

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:

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

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:

PowerShell is a very flexible scripting language that allows users to dynamically create and/or extend objects with additional methods and properties.  This is very useful when you’re trying to build up a rich data set with all of the properties or methods you need.  One important thing that is often overlooked when people are writing scripts that do this is that they can also give those objects a type name.  Why is this type name important?  Three reasons:

1. If you want to further extend those types automatically via a type data file, you’ll want a unique type name so that only the appropriate objects are extended.
2. If you want to apply specific default custom formatting to those types via a format data file, you’ll want a unique name so that only the appropriate objects are formatted this way.
3. If you want to associate specific links and actions with your custom object type in PowerGUI, you’ll want a unique name so that you don’t get links and actions associated with other types.

In practice there are only two use cases where I need to create a custom object type name, and I apply different names depending on the scenario I’m working with at the time.

If I have created a brand new generic PSObject, then I apply a name appropriate to the object.  In this case, after I created my custom object and added the properties, I would do the following:

$myObject.PSObject.TypeNames.Insert(0,’MyObjectTypeName’)

Alternatively, if I am extending an object of a particular type, then I apply an extended type name for that object to the modified version.  In this case, after I created my custom object and added the properties, I would do the following:

$derivedTypeName = $myObject.PSObject.TypeNames[0]
$myObject.PSObject.TypeNames.Insert(0,”$derivedTypeName#MyExtensionName”)

Then if you create type or format data files, you simply need to use your new type name in appropriate XML attribute to set up the association.  Or if you’re adding functionality to PowerGUI, any links and actions you create will automatically be associated with the lowest derived object type, which will be the type name you applied to the object before outputting it in the PowerGUI data grid.

You can add as many type names as you want to your objects, so if you want to create a virtual object hierarchy with your custom object types, and then associate format or type data specifications with derived or base object types, you can do that as well through multiple calls to the Insert method on the TypeNames collection.  This can be useful if you want to share a certain set of functionality between two types of objects you are creating but in addition you want some functionality to be specific to each type and you don’t want to duplicate code.

Hopefully this will encourage you to name your custom object types and define their default properties in scripts that you share with others.

If you’re working with custom objects you should also check out the follow-up post to this that resulted from Hal’s comments on this post, titled “Essential PowerShell: Define default properties for custom objects“.

Enjoy!

Kirk out.

Share this post: