BUGBUG: poor title

PS C:\workspaces\ws1> help tfserver –full

SYNTAX
    Get-TfsServer [-Name] <String> [-Credential <PSCredential>] [-All] [<Common
    Parameters>]   

    Get-TfsServer -Path <String> [-Credential <PSCredential>] [-All] [<CommonPa
    rameters>]

...

  -All
    Get Team Foundation Server object with the extended properties

  Required?                    false
    Position?                    named
    Default value
    Accept pipeline input?       false
    Accept wildcard characters?  false

... 

Not the greatest help text ever written, I know.  Oh well, there’s a lot more room on this blog anyway :)

First the basics: Get-TfsServer and Get-TfsWorkspace (aliases: tfserver, tfworkspace) are intended to be “official” versions of James Manning’s get-tfs.ps1 and get-workspace.ps1 cmdlets.  To incorporate them into the main snap-in, Hyung ported them to C# and standardized the parameters.  Both will now accept either –Path or –Name (but not both).  For tfserver, –Name is the default [position = 1] and all others are named, while the reverse is true for tfworkspace, reflecting what we felt was the most common use of each.  Bottom line, these will all work:

> $tfs = get-tfsserver njtfs
> $tfs = get-tfsserver –path .
> $ws = get-tfsworkspace .
> $ws = get-tfsworkspace –name njtfs
> $ws = get-tfsworkspace –servername .

There are also new parameters like –Credential on tfserver, and –Computer and –Owner on tfworkspace, which behave more or less how you’d expect.  In short, you can use tfserver to interface TFS with Powershell’s built-in credential management features, as well as tfworkspace to query for the Workspace object that represents remote workspaces you may not even own.

So back to the original topic.  The –All switch turns on the special script-friendly behavior that James pioneered and I later extended.

As you can see there are a few differences between the final shipping behavior and the various get-tfs.ps1 scripts floating on the web:

• Once you choose –All, every TFS assembly is loaded immediately, rather than on-demand as you use the ScriptProperties.  The idea here is to “fail early” rather than introduce a ticking bomb into downstream scripts that may depend on these objects.
• The types that we import as NoteProperties are prefixed with the same shorthand as the ScriptProperties, plus an underscore.  Even though we continue to weed out types that aren’t useful (anything private, an exception, or an event) there are still a ton to sort thru; this tweak helps segregate the huge list into “namespaces” that are still marginally navigable with Tab completion.
• C# is a much uglier language to do this work than Powershell!

All in all, you can now do cool things like:

PS C:\workspaces\ws1> $tfs = get-tfsserver njtfs -all
PS C:\workspaces\ws1> $tfs.vcs.GetChangeset(1234)  

Changes Owner                  CreationDa Comment
   etId                                te
------- -----                  ---------- -------
   1234 COATUECAP\LDeGrazia    10/27/2007

PS C:\workspaces\ws1> new-object $tfs.VCS_ChangesetVersionSpec 1234

                            ChangesetId DisplayString
                            ----------- -------------
                                   1234 C1234

So why not have this option switched on permanently?  The vanilla TeamFoundationServer object isn’t very useful on its own; the entire point of James’ original wrapper was to quickly access the VersionControlServer and similar objects.  Well first of all, it’s noticeably slower – on my machine, testing a “cold” Powershell console, the cmdlet takes 3 seconds with the default parameters and 6 seconds with –All.  We’re loading more assemblies than ever, not to mention deep reflection on each one (in order to test an upcast and a string comparison, not exactly speedy operations in themselves).  More importantly, the extra properties add enormous clutter to the objects when not needed.  And I think you’ll be more likely to use those TFS objects in vanilla form in your future scripts.  For example, most of the version control cmdlets in the Fall 2008 suite take a TeamFoundationServer as either pipeline input or a named parameter.  I’m sure whatever Microsoft is cooking up for the next batch will include even more interactivity and flow between cmdlets.

This entry was posted on Tuesday, February 17th, 2009 at 11:59 am and is filed under Powershell, Version Control. You can follow any responses to this entry through the RSS 2.0 feed. You can leave a response, or trackback from your own site.