Shorten Path Names (and using Low Level API functions)

Tobias — Wed, 11 Apr 2012 07:22:00 GMT

Path names can grow large, and sometimes there is just not enough room to display the entire path. There is no cmdlet either that would shorten the path for you. So let's take a look today at how you can access low-level Windows API functions from PowerShell to add this feature,

As an immediate benefit, after you read this article you can optimize your PowerShell prompt and make it shorter while keeping the current path meaningful.

Mission Target: Compacting a Path

What exactly is meant by "shorten a path name"? I am not talking about turning a "long" file path into the old 8.3 file path. That's a different ball game - the 8.3 path would be shorter but at the same time completely unreadable.

What I want is to shorten a path in a human readable format, keeping as much meaningful information as possible. And while there is no PowerShell cmdlet for this, there is a low level Windows API function called PathCompactPathEx() which lives in the system file shlwapi.dll.

In pre-PowerShell-times, low level API functions were only available to developers. With PowerShell, everyone can access them. And here's how.

Accessing Low Level API Functions

To access a low level API function, you need its "signature" which describes where the function lives and how it needs to be called (its parameters and data types). Typically, the signature is defined in a language like c#, but you could as well use signatures defined in any other language that is supported by the .NET framework, like VB.NET. There are plenty of web sites that list API signatures, like pinvoke.net. Here's the signature for PathCompactPathEx() in c#:

[DllImport("shlwapi.dll", CharSet = CharSet.Auto, SetLastError = true)] public static extern bool PathCompactPathEx(System.Text.StringBuilder pszOut, string pszSrc, Int32 cchMax, Int32 dwFlags);

Let's try and decipher it (you can skip this part if your hair is on fire and you just want results):

It tells you that there is a function called PathCompactPathEx() which resides in the system file shlwapi.dll and takes four input parameters and returns a Boolean value. The four parameters needed to run the function have different data types. The first one is a StringBuilder type, the second one is a String (text), and the remainder are Int32 (32bit whole numbers). The signature also states that this is a "static" function. Static functions will later become a part of a data type, so the keyword "static" is an important piece of information once you are ready to call your API function from PowerShell.
And this is how you feed a signature into PowerShell to gain access to that function:

$sig = @'
[DllImport("shlwapi.dll", CharSet = CharSet.Auto, SetLastError = true)]
public static extern bool PathCompactPathEx(
System.Text.StringBuilder pszOut, string pszSrc, Int32 cchMax,
Int32 dwFlags);
'@

Add-Type -MemberDefinition $sig -Namespace Win32 -Name StringFunctions

The secret really is to feed that signature code to the cmdlet Add-Type. This cmdlet then creates a new type (which you can assign any name you want; in this example the type is called Win32.StringFunctions), and you can use the new type then to access the function.

Two things are worth mentioning here:

First, I am submitting the signature as a "Here-String", which is a multiline text delimited by @'…'@. For Here-Strings to work, it is of utmost importance that no text whatsoever (including whitespace) follows the opening tag (@'), and that no text (including whitespace) preceeds the closing tag ('@).

Second, Add-Type is actually taking the c# signature source code and is compiling a DLL in memory which then is loaded. If your signature is written in a different language (like VB.NET), you need to specify the language by adding the parameter -Language. Valid languages currently are CSharp, CSharpVersion3, CSharpVersion2, VisualBasic, and Jscript.

After running Add-Type, you actually get a new type as the name suggests. The name of this type was set by the parameters -Namespace and -Name, so in our example the name of the new type is Win32.StringFunctions. To check out which functions are available in this type, use this line:

PS> [Win32.StringFunctions] | Get-Member -Static

TypeName: Win32.StringFunctions

Name MemberType Definition
---- ---------- ----------
Equals Method static bool Equals(System.Object objA, System.Object objB)
PathCompactPathEx Method static bool PathCompactPathEx(System.Text.StringBuilder p...
ReferenceEquals Method static bool ReferenceEquals(System.Object objA, System.Ob...

And there is our new API function PathCompactPathEx()! Don't worry about the other two, Equals() and ReferenceEquals(), these are default functions provided by every type.

Turning Low-Level Functions Into Civilized Functions

Accessing our low level function is still not a piece of cake, however, because as the term "low level" suggests, these API functions work in a very basic fashion and require you to pay attention to the required data types and containers. That's why it is a best practice to turn a hard-to-use low level function into an easy-to-use PowerShell function before you actually start using it in your scripts.

Here's the result (which you can also download here: http://powershell.com/cs/media/p/15905.aspx):

function Compress-Path($Path, $Length=20) {

$sig = @'
[DllImport("shlwapi.dll", CharSet = CharSet.Auto, SetLastError = true)]
public static extern bool PathCompactPathEx(
System.Text.StringBuilder pszOut, string pszSrc, Int32 cchMax,
Int32 dwFlags);
'@

Add-Type -MemberDefinition $sig -name StringFunctions -namespace Win32

$sb = New-Object System.Text.StringBuilder(260)
if ([Win32.StringFunctions]::PathCompactPathEx($sb , $Path , $Length+1, 0)) {
$sb.ToString()
} else {
Throw "Unable to compact path"
}
}

Now, to compact a path all you need to do is call Compress-Path and tell the function how much room you have:

PS> Compress-Path -Path $env:temp -Length 30
C:\Users\Tobias\AppDat...\Temp
PS>
PS> Compress-Path -Path 'HKLM:\Software\Microsoft\Windows\CurrentVersion\Uninstall' -Len 16
HKL...\Uninstall
PS> Compress-Path -Path 'HKLM:\Software\Microsoft\Windows\CurrentVersion\Uninstall' -Len 30
HKLM:\Software\Mi...\Uninstall

A better PowerShell prompt

One first use of Compress-Path could be an improved prompt function. By default, the PowerShell prompt always displays the complete path you are in, often wasting a lot of real estate in your console or editor.

Here's an improved prompt function that displays a compressed path, still giving you a good indication of where your current folder is, and displays the complete path in your window title bar.

function prompt {
'PS {0}> ' -f (Compress-Path (Get-Location) 15)
$host.UI.RawUI.WindowTitle = (Get-Location)
}

To permanently use this prompt, just make sure you add both the function Compress-Path and the function prompt into your profile script so PowerShell loads both functions automatically at startup (both functions can be downloaded here: http://powershell.com/cs/media/p/15905.aspx). The profile script is located here:

PS C:\Us...\Tobias> $profile.CurrentUserAllHosts
C:\Users\Tobias\Documents\WindowsPowerShell\profile.ps1

And here's some code that opens the profile script for you (and creates it if it does not yet exist):

if (!(Test-Path $profile.CurrentUserAllHosts))
{ $null = New-Item $profile.CurrentUserAllHosts -Force -ItemType File };
Invoke-Item $profile.CurrentUserAllHosts

I hope you had fun! You can now take this concept and wrap all kinds of low-level API functions in the same way. Stay tuned...!

Tobias

Microsoft MVP PowerShell Germany

P.S.
If you live in Germany or other parts of Europe and your company would like to set up a truly great PowerShell training, just contact me! I regularly train mid- to large-size companies. Trainings are always a blast with tons of real-world-examples and solutions. Here's how to get in touch with me: tobias.weltner@scriptinternals.de

Dreaming in PowerShell : prompt

Shorten Path Names (and using Low Level API functions)

Mission Target: Compacting a Path

Accessing Low Level API Functions

Turning Low-Level Functions Into Civilized Functions

A better PowerShell prompt