{"id":4663,"date":"2005-10-25T15:41:00","date_gmt":"2005-10-25T15:41:00","guid":{"rendered":"https:\/\/blogs.msdn.microsoft.com\/buckh\/2005\/10\/25\/displaying-the-labels-on-a-file-including-label-comments\/"},"modified":"2005-10-25T15:41:00","modified_gmt":"2005-10-25T15:41:00","slug":"displaying-the-labels-on-a-file-including-label-comments","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/buckh\/displaying-the-labels-on-a-file-including-label-comments\/","title":{"rendered":"Displaying the labels on a file, including label comments"},"content":{"rendered":"

Unfortunately, there’s not a fast, efficient way to see the list of labels in the system with the full comment without also seeing a list of all of the files included in a label.  You also can’t efficiently answer the question, “What labels involve foo.cs?”  While this won’t be changed for v1, you can certainly do it using code.  I mentioned on the TFS forum<\/A> that I’d try to put together a piece of code to do this.  The result is the code below.<\/P>\n

The code is really simple to do this, but I ended up adding more to it than I originally intended.  All that’s really necessary here is to call QueryLabels() to get the information we need.<\/P>\n

Let’s look at the QueryLabels() call in a little detail, since it is the heart of the app.  Here is the method declaration from the VersionControlServer class.<\/P>\n

\n

public VersionControlLabel[] QueryLabels(String labelName,
                                         <\/FONT>String labelScope,
                                         String owner, 
                                         bool includeItems,
                                         String filterItem,
                                         VersionSpec versionFilterItem)<\/FONT><\/P><\/BLOCKQUOTE>\n

By convention, methods that begin with “Query” in the source control API allow you to pass null to mean “give me everything.”  In the code below, I don’t want to filter by labelName<\/FONT> or owner<\/FONT>, so I set those to null to include everything.<\/P>\n

If the user specified a server path for the scope (scope is always a server path and not a local path), we’ll use it, and otherwise we’ll use the root ($\/).  The scope of a label is, effectively, the part of the tree where it has ownership of that label name.  In other words by specifying the label scope, $\/A and $\/B can have separate labels named Foo, but no new label Foo can be used under $\/A or $\/B.  For this program, setting the scope simply narrows the part of the tree it will include in the output.  For example, running this with a scope of $\/A would show only one label called Foo, but running it with $\/ as the scope (or omitting the scope) would result in two Foo labels being printed.<\/P>\n

\n

D:\\ws1>tree
Folder PATH listing for volume Dev
Volume serial number is 0006EE50 185C:793F
D:.
\u251c\u2500\u2500\u2500A
\u2514\u2500\u2500\u2500B<\/FONT><\/P>\n

D:\\ws1>tf label <\/FONT>Foo@$\/testproj\/A<\/FONT> A
Created label <\/FONT>Foo@$\/testproj\/A<\/FONT><\/P>\n

D:\\ws1>tf label <\/FONT>Foo@$\/testproj\/B<\/FONT> B
Created label <\/FONT>Foo@$\/testproj\/B<\/FONT><\/P>\n

D:\\ws1>d:\\LabelHistory\\LabelHistory\\bin\\Debug\\LabelHistory.exe
Foo (10\/25\/2005 4:00 PM)
Foo (10\/25\/2005 4:00 PM)<\/FONT><\/P><\/BLOCKQUOTE>\n

The most important parameter here is actually includeItems<\/FONT>.  By setting this parameter to false, we’ll get the label metadata without getting the list of files and folders that are in the label.  This saves both a ton of bandwidth as well as load on the server for any query involving real-world labels that include many thousands of files.<\/P>\n

The remaining parameters are filterItem<\/FONT> and versionFilterItem<\/FONT>.  The filterItem<\/FONT> parameter allows you to specify a server or local path whereby the query results will only include labels involving that file or folder.  It allows you to answer the question, “What labels have been applied to file foo.cs?”  The versionFilterItem<\/FONT> is used to specify what version of the item had the specified path.  It’s an unfortunate complexity that’s due to the fact that we support rename (e.g., A was called Z at changeset 12, F at changeset 45, and A at changeset 100 and beyond).  Before your eyes glaze over (they haven’t already, right?), I just set that parameter to latest.<\/P>\n

Here’s an example of using the program with the tree mentioned earlier.  I modified the Foo label on A to have a comment, so it has a later modification time.<\/P>\n

\n

D:\\ws1>tf label Foo@$\/testproj\/A \/comment:”This is the first label I created.”
Updated label Foo@$\/testproj\/A<\/FONT><\/P>\n

D:\\ws1>d:\\LabelHistory\\LabelHistory\\bin\\Debug\\LabelHistory.exe
Foo (10\/25\/2005 4:05 PM)
   Comment: This is the first label I created.
Foo (10\/25\/2005 4:00 PM)<\/FONT><\/P><\/BLOCKQUOTE>\n

Then I added a file under A, called a.txt, and modified the label to include it.  Running the app on A\\a.txt, we see that it is only involved in one of the two labels in the system.<\/P>\n

\n

D:\\ws1>tf label <\/FONT>Foo@$\/testproj\/A<\/FONT> A\\a.txt
Updated label <\/FONT>Foo@$\/testproj\/A<\/FONT><\/P>\n

D:\\ws1>d:\\LabelHistory\\LabelHistory\\bin\\Debug\\LabelHistory.exe A\\a.txt
Foo (10\/25\/2005 4:56 PM)
   Comment: This is the first label I created.<\/FONT><\/P><\/BLOCKQUOTE>\n

To build it, you can create a Windows console app in Visual Studio, drop this code into it, and add the following references to the VS project.<\/P>\n

\n

Microsoft.TeamFoundation.Client
Microsoft.TeamFoundation.Common
Microsoft.TeamFoundation.VersionControl.Client
Microsoft.TeamFoundation.VersionControl.Common<\/P><\/BLOCKQUOTE>

using<\/SPAN> System;\nusing<\/SPAN> System.IO;\nusing<\/SPAN> Microsoft.TeamFoundation;\nusing<\/SPAN> Microsoft.TeamFoundation.Client;\nusing<\/SPAN> Microsoft.TeamFoundation.VersionControl.Client;\nusing<\/SPAN> Microsoft.TeamFoundation.VersionControl.Common;<\/p>\n
namespace<\/SPAN> LabelHistory\n{\n    class<\/SPAN> Program\n    {\n        static<\/SPAN> void<\/SPAN> Main(string<\/SPAN>[] args)\n        {\n            \/\/ Check and get the arguments.<\/SPAN>\n            String path, scope;\n            VersionControlServer sourceControl;\n            GetPathAndScope(args, out<\/SPAN> path, out<\/SPAN> scope, out<\/SPAN> sourceControl);<\/p>\n
            \/\/ Retrieve and print the label history for the file.<\/SPAN>\n            VersionControlLabel[] labels = null<\/SPAN>;\n            try<\/SPAN>\n            {\n                \/\/ The first three arguments here are null because we do not<\/SPAN>\n                \/\/ want to filter by label name, scope, or owner.<\/SPAN>\n                \/\/ Since we don’t need the server to send back the items in<\/SPAN>\n                \/\/ the label, we get much better performance by ommitting<\/SPAN>\n                \/\/ those through setting the fourth parameter to false.<\/SPAN>\n                labels = sourceControl.QueryLabels(null<\/SPAN>, scope, null<\/SPAN>, false<\/SPAN>, \n                                                   path, VersionSpec.Latest);\n            }\n            catch<\/SPAN> (TeamFoundationServerException e)\n            {\n                \/\/ We couldn’t contact the server, the item wasn’t found,<\/SPAN>\n                \/\/ or there was some other problem reported by the server,<\/SPAN>\n                \/\/ so we stop here.<\/SPAN>\n                Console.Error.WriteLine(e.Message);\n                Environment.Exit(1<\/SPAN>);\n            }<\/p>\n
            if<\/SPAN> (labels.Length == 0<\/SPAN>)\n            {\n                Console.WriteLine(“There are no labels for “<\/SPAN> + path);\n            }\n            else<\/SPAN>\n            {\n                foreach<\/SPAN> (VersionControlLabel label in<\/SPAN> labels)\n                {\n                    \/\/ Display the label’s name and when it was last modified.<\/SPAN>\n                    Console.WriteLine(“{0} ({1})”<\/SPAN>, label.Name,\n                                      label.LastModifiedDate.ToString(“g”<\/SPAN>));<\/p>\n
                    \/\/ For labels that actually have comments, display it.<\/SPAN>\n                    if<\/SPAN> (label.Comment.Length > 0<\/SPAN>)\n                    {\n                        Console.WriteLine(”   Comment: “<\/SPAN> + label.Comment);\n                    }\n                }\n            }\n        }<\/p>\n
        private<\/SPAN> static<\/SPAN> void<\/SPAN> GetPathAndScope(String[] args,\n                                            out<\/SPAN> String path, out<\/SPAN> String scope,\n                                            out<\/SPAN> VersionControlServer sourceControl)\n        {\n            \/\/ This little app takes either no args or a file path and optionally a scope.<\/SPAN>\n            if<\/SPAN> (args.Length > 2<\/SPAN> || \n                args.Length == 1<\/SPAN> && args[0<\/SPAN>] == “\/?”<\/SPAN>)\n            {\n                Console.WriteLine(“Usage: labelhist”<\/SPAN>);\n                Console.WriteLine(”       labelhist path [label scope]”<\/SPAN>);\n                Console.WriteLine();\n                Console.WriteLine(“With no arguments, all label names and comments are displayed.”<\/SPAN>);\n                Console.WriteLine(“If a path is specified, only the labels containing that path”<\/SPAN>);\n                Console.WriteLine(“are displayed.”<\/SPAN>);\n                Console.WriteLine(“If a scope is supplied, only labels at or below that scope will”<\/SPAN>);\n                Console.WriteLine(“will be displayed.”<\/SPAN>);\n                Console.WriteLine();\n                Console.WriteLine(“Examples: labelhist c:\\\\projects\\\\secret\\\\notes.txt”<\/SPAN>);\n                Console.WriteLine(”          labelhist $\/secret\/notes.txt”<\/SPAN>);\n                Console.WriteLine(”          labelhist c:\\\\projects\\\\secret\\\\notes.txt $\/secret”<\/SPAN>);\n                Environment.Exit(1<\/SPAN>);\n            }<\/p>\n
            \/\/ Figure out the server based on either the argument or the<\/SPAN>\n            \/\/ current directory.<\/SPAN>\n            WorkspaceInfo wsInfo = null<\/SPAN>;\n            if<\/SPAN> (args.Length < 1<\/SPAN>)\n            {\n                path = null<\/SPAN>;\n            }\n            else<\/SPAN>\n            {\n                path = args[0<\/SPAN>];\n                try<\/SPAN>\n                {\n                    if<\/SPAN> (!VersionControlPath.IsServerItem(path))\n                    {\n                        wsInfo = Workstation.Current.GetLocalWorkspaceInfo(path);\n                    }\n                }\n                catch<\/SPAN> (Exception e)\n                {\n                    \/\/ The user provided a bad path argument.<\/SPAN>\n                    Console.Error.WriteLine(e.Message);\n                    Environment.Exit(1<\/SPAN>);\n                }\n            }<\/p>\n
            if<\/SPAN> (wsInfo == null<\/SPAN>)\n            {\n                wsInfo = Workstation.Current.GetLocalWorkspaceInfo(Environment.CurrentDirectory);\n            }<\/p>\n
            \/\/ Stop if we couldn’t figure out the server.<\/SPAN>\n            if<\/SPAN> (wsInfo == null<\/SPAN>)\n            {\n                Console.Error.WriteLine(“Unable to determine the server.”<\/SPAN>);\n                Environment.Exit(1<\/SPAN>);\n            }<\/p>\n
            TeamFoundationServer tfs =\n                TeamFoundationServerFactory.GetServer(wsInfo.ServerName);\n                                                      \/\/ RTM: wsInfo.ServerUri.AbsoluteUri);<\/SPAN>\n            sourceControl = (VersionControlServer)tfs.GetService(typeof<\/SPAN>(VersionControlServer));<\/p>\n
            \/\/ Pick up the label scope, if supplied.<\/SPAN>\n            scope = VersionControlPath.RootFolder;\n            if<\/SPAN> (args.Length == 2<\/SPAN>)\n            {\n                \/\/ The scope must be a server path, so we convert it here if<\/SPAN>\n                \/\/ the user specified a local path.<\/SPAN>\n                if<\/SPAN> (!VersionControlPath.IsServerItem(args[1<\/SPAN>]))\n                {\n                    Workspace workspace = wsInfo.GetWorkspace(tfs);\n                    scope = workspace.GetServerItemForLocalItem(args[1<\/SPAN>]);\n                }\n                else<\/SPAN>\n                {\n                    scope = args[1<\/SPAN>];\n                }\n            }\n        }\n    }\n}<\/PRE>
<\/FONT><\/PRE>\n
[Update 10\/26] I added Microsoft.TeamFoundation.Common to the list of assemblies to reference.<\/P>\n
[Update 7\/12\/06]  Jeff Atwood posted a VS solution containing this code and a binary.  You can find it at the end of http:\/\/blogs.vertigosoftware.com\/teamsystem\/archive\/2006\/07\/07\/Listing_all_Labels_attached_to_a_file_or_folder.aspx<\/A>.<\/P><\/p>\n","protected":false},"excerpt":{"rendered":"
Unfortunately, there’s not a fast, efficient way to see the list of labels in the system with the full comment without also seeing a list of all of the files included in a label.  You also can’t efficiently answer the question, “What labels involve foo.cs?”  While this won’t be changed for v1, you can certainly do it using code.  […]<\/p>\n","protected":false},"author":94,"featured_media":10268,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[1],"tags":[6,8,15],"class_list":["post-4663","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-uncategorized","tag-source-control","tag-team-foundation","tag-tfs-api"],"acf":[],"blog_post_summary":"
Unfortunately, there’s not a fast, efficient way to see the list of labels in the system with the full comment without also seeing a list of all of the files included in a label.  You also can’t efficiently answer the question, “What labels involve foo.cs?”  While this won’t be changed for v1, you can certainly do it using code.  […]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/buckh\/wp-json\/wp\/v2\/posts\/4663","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/buckh\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/buckh\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/buckh\/wp-json\/wp\/v2\/users\/94"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/buckh\/wp-json\/wp\/v2\/comments?post=4663"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/buckh\/wp-json\/wp\/v2\/posts\/4663\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/buckh\/wp-json\/wp\/v2\/media\/10268"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/buckh\/wp-json\/wp\/v2\/media?parent=4663"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/buckh\/wp-json\/wp\/v2\/categories?post=4663"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/buckh\/wp-json\/wp\/v2\/tags?post=4663"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}