> pshdo

Online Carbon Help

The current version of the Carbon help is now online. There are still a lot of functions that have little to no documentation. Now that I’ve put it online, and have automated scripts that will generate it for me, I’ll be steadily improving the documentation. It’s my number one priority before I release version 1.0.

I’m using a heavily-modified version of Out-Html to convert the built-in help to HTML. All the description and example explanations in the help are written using Markdown, and I’m using MarkdownSharp to convert to HTML.

The only outstanding improvement I’d like to make to the online help is to create links from type names to their MSDN documentation.

Beware Get-ChildItem

I discovered today that the Get-ChildItem cmdlet wasn’t behaving as I expected. Passing it $null, @(), or '' will return the contents of the current directory:

> Get-ChildItem .


   Directory: C:\Temp\BewareGetChildItem

Mode                LastWriteTime     Length Name
----                -------------     ------ ----
-a---          5/4/2012   4:08 PM          6 Get-ChildItem.txt


> Get-ChildItem $null


   Directory: C:\Temp\BewareGetChildItem

Mode                LastWriteTime     Length Name
----                -------------     ------ ----
-a---          5/4/2012   4:08 PM          6 Get-ChildItem.txt


> Get-ChildItem @()


   Directory: C:\Temp\BewareGetChildItem

Mode                LastWriteTime     Length Name
----                -------------     ------ ----
-a---          5/4/2012   4:08 PM          6 Get-ChildItem.txt


> Get-ChildItem ''


   Directory: C:\Temp\BewareGetChildItem

Mode                LastWriteTime     Length Name
----                -------------     ------ ----
-a---          5/4/2012   4:08 PM          6 Get-ChildItem.txt

Yikes! I would expect it to write an error or just return nothing.

We have a function in our website deployment script that takes in a list of items and a filter, and deletes any item that doesn’t match the filter, like this:

function Remove-ExtraFiles($Items, $Exclude)
{
    Get-ChildItem $Items -Exclude $Exclude -Recurse |
        Where-Object { -not $_.PsIsContainer } |
        Remove-Item
}

I was testing this script when I saw that files under my local directory were getting deleted. By the time I killed the script, it was too late: the last two hours of work were gone. It turns out that Remove-ExtraFiles was getting called with an empty array as the $Items parameter value.

In my case, the solution was to add some validation to the $Items parameter:

function Remove-ExtraFiles
{
    param(
        [Parameter(Mandatory=$true)]
        [string[]]
        $Items,

        [string[]]
        $Exclude)
    )
    Get-ChildItem $Items -Exclude $Exclude -Recurse |
        Where-Object { -not $_.PsIsContainer } |
        Remove-Item
}

Making the parameter mandatory causes a script error if calling Remove-ExtraFiles with null, an empty array, or an empty string.

New-Website

In Feburary 2011, I finally got tired of using MSBuild as a scripting language. There are great frameworks out there that make it bearable, but trying to use a build language to script and program is a recipe for disaster and bloated scripts.

I don’t know what finally motivated me to learn PowerShell. I ordered every PowerShell book from the library, but returned them as soon as I started Lee Holmes' PowerShell Cookbook. Within a few days, I was writing scripts. A year later, I have a hard time writing MSBuild.

I’m still kicking myself for waiting as long as I did. I had heard lots of respectable developers extol PowerShell, but I never set aside the time to learn it. What a waste.

If you’re a .NET developer, and still using cmd as your command prompt, or even worse cygwin (shudder), shame on you! Take a deep breath, two days off, and read Lee Holmes' book. You’ll never look back.