example usage of VersionControlServer.CreateLabel

Like many other version control systems, Team Foundation’s version control has the concept of labels.  It’s a useful way of identifying a collection of particular versions of a set of items, especially if that collection is at different points in time (so you couldn’t just say “changeset 12345” because some are before or after that point in time).

One interesting thing that TFVC labels have over most other systems is the concept of label scoping.  Since a given TFS server can contain hundreds of Team Projects, it’s not very useful if you could only have 1 label called “beta2”, so with TFVC labels (which default in scope to the team project) you can have separate labels called beta2 at scopes of $/proj1, $/proj2, and $/proj3/subproj7.

On a related note, the RTM bits have a (ignorable) bug around constructing new VersionControlLabel instances, so keep that in mind.

Note that in this example, we’re passing VersionSpec.Latest, but we could just as easily pass a different specific version (for instance “new ChangesetVersionSpec(123)” or “new DateVersionSpec(DateTime.Now)” or whatever)

C:\>CreateLabelExample.exe http://jmanning-test:8080 foobarbaz $/proj/foo.cs $/proj/src/a $/proj/tgt/b
Successfully created label foobarbaz

C:\>tf labels /format:detailed

Label  : foobarbaz
Scope  : $/proj
Owner  : jmanning
Date   : Tuesday, August 08, 2006 11:53:19 AM
Comment: Example label showing API usage

Changeset Item
——— ———————————————————————-
5         $/proj/foo.cs
4         $/proj/src/a
4         $/proj/tgt/b

Source (also attached as a solution)

using System;


using Microsoft.TeamFoundation.Client;

using Microsoft.TeamFoundation.VersionControl.Client;


namespace CreateLabelExample


    class Program


        static void Main(string[] args)


            if (args.Length < 3)


                Console.Error.WriteLine(“Usage: CreateLabelExample <server> <labelName> <item1> [<item2>…]”);



            string serverName = args[0];

            string labelName = args[1];


            TeamFoundationServer tfs = TeamFoundationServerFactory.GetServer(serverName);

            VersionControlServer vcs = (VersionControlServer)tfs.GetService(typeof(VersionControlServer));


            // What label do we want to construct?

            string labelOwner = vcs.AuthenticatedUser;

            string labelScope = “$/proj”;

            string labelComment = “Example label showing API usage”;

            VersionControlLabel labelToCreate = new VersionControlLabel(vcs,






            // What items should this label apply to?

            LabelItemSpec[] labelItemSpecs = new LabelItemSpec[args.Length – 2];

            for (int i = 2; i < args.Length; i++)


                // Create the ItemSpec referring to the particular item (but not a particular version)

                ItemSpec itemSpec = new ItemSpec(args[i], RecursionType.None);

                // Construct the LabelItemSpec to add in the version information

                labelItemSpecs[i-2] = new LabelItemSpec(itemSpec, VersionSpec.Latest, false);



            // Construct the label

            vcs.CreateLabel(labelToCreate, labelItemSpecs, LabelChildOption.Replace);


            Console.WriteLine(“Successfully created label {0}”, labelToCreate.Name);







Comments (6)

  1. Buck Hodges says:

    I recently had to put together a list of links to code samples.&amp;nbsp; This isn’t even close to comprehensive,…

  2. Buck Hodges says:

    I recently had to put together a list of links to code samples.&amp;nbsp; This isn’t even close to comprehensive,…

  3. Abhinaba on Team Build Ticker – Parting Gift.

    Brian Harry on TFS Trial Edition and Release Candidate…

  4. A recent request : "I want to be able to add a label to all files that were modified/added/whatever as

  5. Buck Hodges says:

    I recently had to put together a list of links to code samples. This isn’t even close to comprehensive,