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 https://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>...]");
Environment.Exit(1);
}
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,
labelName,
labelOwner,
labelScope,
labelComment);
// 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);
}
}
}