Get-TfsItemProperty is the bridge between server and local objects
Most of the real-world examples of the TFS powershell tool revolve around querying (and possibly updating) the state of the server.
And rightfully so: most of the operations you want to do locally are already possible without any special tools. The â€œPowershell snap-in systemâ€ we know and love today was created to help IT admins manage their servers â€“ even today, only a brave few developers have completely replaced cmd.exe at their daily workstation.
Nevertheless, we shouldnâ€™t be satisfied to have our TFS cmdlets live in their own little world. Luckily, all the info we could ever want about a TFS version controlled item â€“ including its local state â€“ comes packaged in the ExtendedItem object. Even more fortuitously, if you revisit the exploration of QualifiedItemSpec with an eye for detail, youâ€™ll notice that one overload of ToQualifiedItem() is not like the others.* In the constructor where ExtendedItem decays into QualifiedItem, the properties saved into the resulting tuple include LocalItem and VersionLocal instead of more familiar ones like ServerItem. This is not a coincidence :)
Letâ€™s sum up what we know so far. Native TFS objects are funneled down the pipeline by stripping them to bare essentials about the items they represent (QIs); these serve as a common interface between cmdlets. When an ExtendedItem is stripped down, the next cmdlet will use the local filename & local version info as its parameters. Get-TfsItemProperty is the cmdlet that returns ExtendedItems. Capiche?
Time to put our newfound knowledge into action. If youâ€™ve also been following the last several posts on file manipulation in powershell, these examples will hopefully inspire an â€œaha!â€ moment.
[Note that I have get-tfsitemproperty aliased to â€˜tfpropâ€™ rather than â€˜tfpropertiesâ€™ as it appears in a default install of the Power Tools.]
Are we having fun yet?!
So far weâ€™ve only really exercised the filename part of the QI. Equally interesting things happen when you take advantage of the special ability that Get-TfsItemProperty offers to manipulate the local version.
[Microsofties: think bbpack / jjpack]
Opens up a whole new world of TFVC scripting mania, wouldnâ€™t ya say?
*Iâ€™ll admit the one for GettingEventArgs is a little funky as well. Here, the choice of properties to expose came down to UX / gut feel. TargetLocalItem is usually what you want to see; it tends to be the â€œfinal resultâ€ of mainline operations, surviving things like Rename and Undo fairly well. But itâ€™s not always the best choice. Obviously when itâ€™s null we need a backup; good old ServerItem will do. Itâ€™s [almost always] guaranteed to be present, but itâ€™s not always perfect either â€“ now you have the occasional strange appearance of server paths in your list of local files being touched by the Update. Finding the right info gets really tricky really fast: was TargetLocalItem null because of a pending Delete, because itâ€™s cloaked or otherwise excluded from our workspace, or because weâ€™re undoing a pending Branch or Merge? Thatâ€™s just one example. The logic behind which name tf.exe displays in which scenario is actually one of the more complex pieces of the app. With powershell we can accept â€œgood enoughâ€ since the object model lets you manipulate things to your heartâ€™s content.